@react-navigation/native-stack 6.2.4 → 6.4.1

package/src/navigators/createNativeStackNavigator.tsx

@@ -25,18 +25,19 @@ function NativeStackNavigator({
   screenOptions,
   ...rest
 }: NativeStackNavigatorProps) {
-  const { state, descriptors, navigation } = useNavigationBuilder<
-    StackNavigationState<ParamListBase>,
-    StackRouterOptions,
-    StackActionHelpers<ParamListBase>,
-    NativeStackNavigationOptions,
-    NativeStackNavigationEventMap
-  >(StackRouter, {
-    initialRouteName,
-    children,
-    screenListeners,
-    screenOptions,
-  });
+  const { state, descriptors, navigation, NavigationContent } =
+    useNavigationBuilder<
+      StackNavigationState<ParamListBase>,
+      StackRouterOptions,
+      StackActionHelpers<ParamListBase>,
+      NativeStackNavigationOptions,
+      NativeStackNavigationEventMap
+    >(StackRouter, {
+      initialRouteName,
+      children,
+      screenListeners,
+      screenOptions,
+    });
 
   React.useEffect(
     () =>
@@ -64,12 +65,14 @@ function NativeStackNavigator({
   );
 
   return (
-    <NativeStackView
-      {...rest}
-      state={state}
-      navigation={navigation}
-      descriptors={descriptors}
-    />
+    <NavigationContent>
+      <NativeStackView
+        {...rest}
+        state={state}
+        navigation={navigation}
+        descriptors={descriptors}
+      />
+    </NavigationContent>
   );
 }
 

package/src/types.tsx

@@ -85,20 +85,23 @@ export type NativeStackHeaderProps = {
   navigation: NativeStackNavigationProp<ParamListBase>;
 };
 
-export type HeaderBackButtonProps = {
+export type HeaderButtonProps = {
   /**
    * Tint color for the header.
    */
   tintColor?: string;
+  /**
+   * Whether it's possible to navigate back in stack.
+   */
+  canGoBack: boolean;
+};
+
+export type HeaderBackButtonProps = HeaderButtonProps & {
   /**
    * Label text for the button. Usually the title of the previous screen.
    * By default, this is only shown on iOS.
    */
   label?: string;
-  /**
-   * Whether it's possible to navigate back in stack.
-   */
-  canGoBack: boolean;
 };
 
 export type NativeStackNavigationOptions = {
@@ -179,6 +182,7 @@ export type NativeStackNavigationOptions = {
    *
    * For large title to collapse on scroll, the content of the screen should be wrapped in a scrollable view such as `ScrollView` or `FlatList`.
    * If the scrollable area doesn't fill the screen, the large title won't collapse on scroll.
+   * You also need to specify `contentInsetAdjustmentBehavior="automatic"` in your `ScrollView`, `FlatList` etc.
    *
    * Only supported on iOS.
    *
@@ -245,6 +249,12 @@ export type NativeStackNavigationOptions = {
    * Tint color for the header. Changes the color of back button and title.
    */
   headerTintColor?: string;
+  /**
+   * Function which returns a React Element to render as the background of the header.
+   * This is useful for using backgrounds such as an image, a gradient, blur effect etc.
+   * You can use this with `headerTransparent` to render content underneath a translucent header.
+   */
+  headerBackground?: () => React.ReactNode;
   /**
    * Function which returns a React Element to display on the left side of the header.
    * This replaces the back button. See `headerBackVisible` to show the back button along side left element.
@@ -253,7 +263,7 @@ export type NativeStackNavigationOptions = {
   /**
    * Function which returns a React Element to display on the right side of the header.
    */
-  headerRight?: (props: { tintColor?: string }) => React.ReactNode;
+  headerRight?: (props: HeaderButtonProps) => React.ReactNode;
   /**
    * String or a function that returns a React Element to be used by the header.
    * Defaults to screen `title` or route name.
@@ -295,9 +305,11 @@ export type NativeStackNavigationOptions = {
     }
   >;
   /**
-   * Options to render a native search bar on iOS.
+   * Options to render a native search bar.
+   * You also need to specify `contentInsetAdjustmentBehavior="automatic"` in your `ScrollView`, `FlatList` etc.
+   * If you don't have a `ScrollView`, specify `headerTransparent: false`.
    *
-   * @platform ios
+   * Only supported on iOS and Android.
    */
   headerSearchBarOptions?: SearchBarProps;
   /**

package/src/views/HeaderConfig.tsx

@@ -10,6 +10,7 @@ import {
 } from 'react-native';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import {
+  isSearchBarAvailableForCurrentPlatform,
   ScreenStackHeaderBackButtonImage,
   ScreenStackHeaderCenterView,
   ScreenStackHeaderConfig,
@@ -23,11 +24,13 @@ import type { NativeStackNavigationOptions } from '../types';
 import { processFonts } from './FontProcessor';
 
 type Props = NativeStackNavigationOptions & {
+  headerHeight: number;
   route: Route<string>;
   canGoBack: boolean;
 };
 
 export default function HeaderConfig({
+  headerHeight,
   headerBackImageSource,
   headerBackButtonMenuEnabled,
   headerBackTitle,
@@ -39,6 +42,7 @@ export default function HeaderConfig({
   headerLargeTitle,
   headerLargeTitleShadowVisible,
   headerLargeTitleStyle,
+  headerBackground,
   headerLeft,
   headerRight,
   headerShown,
@@ -55,6 +59,7 @@ export default function HeaderConfig({
   canGoBack,
 }: Props): JSX.Element {
   const insets = useSafeAreaInsets();
+
   const { colors } = useTheme();
   const tintColor =
     headerTintColor ?? (Platform.OS === 'ios' ? colors.primary : colors.text);
@@ -96,20 +101,28 @@ export default function HeaderConfig({
 
   const headerLeftElement = headerLeft?.({
     tintColor,
+    canGoBack,
     label: headerBackTitle,
+  });
+  const headerRightElement = headerRight?.({
+    tintColor,
     canGoBack,
   });
-  const headerRightElement = headerRight?.({ tintColor });
   const headerTitleElement =
     typeof headerTitle === 'function'
       ? headerTitle({ tintColor, children: titleText })
       : null;
 
-  if (
-    Platform.OS === 'ios' &&
-    headerSearchBarOptions != null &&
-    SearchBar == null
-  ) {
+  const supportsHeaderSearchBar =
+    typeof isSearchBarAvailableForCurrentPlatform === 'boolean'
+      ? isSearchBarAvailableForCurrentPlatform
+      : // Fallback for older versions of react-native-screens
+        Platform.OS === 'ios' && SearchBar != null;
+
+  const hasHeaderSearchBar =
+    supportsHeaderSearchBar && headerSearchBarOptions != null;
+
+  if (headerSearchBarOptions != null && !supportsHeaderSearchBar) {
     throw new Error(
       `The current version of 'react-native-screens' doesn't support SearchBar in the header. Please update to the latest version to use this option.`
     );
@@ -124,105 +137,132 @@ export default function HeaderConfig({
     ? headerLeftElement != null
     : Platform.OS === 'android' && headerTitleElement != null;
 
+  const translucent =
+    headerBackground != null ||
+    headerTransparent ||
+    // When using a SearchBar or large title, the header needs to be translucent for it to work on iOS
+    ((hasHeaderSearchBar || headerLargeTitle) &&
+      Platform.OS === 'ios' &&
+      headerTransparent !== false);
+
   return (
-    <ScreenStackHeaderConfig
-      backButtonInCustomView={backButtonInCustomView}
-      backgroundColor={
-        headerStyleFlattened.backgroundColor ??
-        (headerTransparent ? 'transparent' : colors.card)
-      }
-      backTitle={headerBackTitleVisible ? headerBackTitle : ' '}
-      backTitleFontFamily={backTitleFontFamily}
-      backTitleFontSize={headerBackTitleStyleFlattened.fontSize}
-      blurEffect={headerBlurEffect}
-      color={tintColor}
-      direction={I18nManager.isRTL ? 'rtl' : 'ltr'}
-      disableBackButtonMenu={headerBackButtonMenuEnabled === false}
-      hidden={headerShown === false}
-      hideBackButton={headerBackVisible === false}
-      hideShadow={headerShadowVisible === false}
-      largeTitle={headerLargeTitle}
-      largeTitleBackgroundColor={headerLargeStyleFlattened.backgroundColor}
-      largeTitleColor={headerLargeTitleStyleFlattened.color}
-      largeTitleFontFamily={largeTitleFontFamily}
-      largeTitleFontSize={headerLargeTitleStyleFlattened.fontSize}
-      largeTitleFontWeight={headerLargeTitleStyleFlattened.fontWeight}
-      largeTitleHideShadow={headerLargeTitleShadowVisible === false}
-      title={typeof headerTitle === 'string' ? headerTitle : titleText}
-      titleColor={titleColor}
-      titleFontFamily={titleFontFamily}
-      titleFontSize={titleFontSize}
-      titleFontWeight={titleFontWeight}
-      topInsetEnabled={insets.top !== 0}
-      translucent={
-        // This defaults to `true`, so we can't pass `undefined`
-        headerTransparent === true
-      }
-    >
-      {Platform.OS === 'ios' ? (
-        <>
-          {headerLeftElement != null ? (
-            <ScreenStackHeaderLeftView>
-              {headerLeftElement}
-            </ScreenStackHeaderLeftView>
-          ) : null}
-          {headerTitleElement != null ? (
-            <ScreenStackHeaderCenterView>
-              {headerTitleElement}
-            </ScreenStackHeaderCenterView>
-          ) : null}
-        </>
-      ) : (
-        <>
-          {headerLeftElement != null || typeof headerTitle === 'function' ? (
-            <ScreenStackHeaderLeftView>
-              <View style={styles.row}>
-                {headerLeftElement}
-                {headerTitleAlign !== 'center' ? (
-                  typeof headerTitle === 'function' ? (
-                    headerTitleElement
-                  ) : (
-                    <HeaderTitle
-                      tintColor={tintColor}
-                      style={headerTitleStyleSupported}
-                    >
-                      {titleText}
-                    </HeaderTitle>
-                  )
-                ) : null}
-              </View>
-            </ScreenStackHeaderLeftView>
-          ) : null}
-          {headerTitleAlign === 'center' ? (
-            <ScreenStackHeaderCenterView>
-              {typeof headerTitle === 'function' ? (
-                headerTitleElement
-              ) : (
-                <HeaderTitle
-                  tintColor={tintColor}
-                  style={headerTitleStyleSupported}
-                >
-                  {titleText}
-                </HeaderTitle>
-              )}
-            </ScreenStackHeaderCenterView>
-          ) : null}
-        </>
-      )}
-      {headerBackImageSource !== undefined ? (
-        <ScreenStackHeaderBackButtonImage source={headerBackImageSource} />
-      ) : null}
-      {headerRightElement != null ? (
-        <ScreenStackHeaderRightView>
-          {headerRightElement}
-        </ScreenStackHeaderRightView>
-      ) : null}
-      {Platform.OS === 'ios' && headerSearchBarOptions != null ? (
-        <ScreenStackHeaderSearchBarView>
-          <SearchBar {...headerSearchBarOptions} />
-        </ScreenStackHeaderSearchBarView>
+    <>
+      {headerBackground != null ? (
+        <View
+          style={[
+            styles.background,
+            headerTransparent ? styles.translucent : null,
+            { height: headerHeight },
+          ]}
+        >
+          {headerBackground()}
+        </View>
       ) : null}
-    </ScreenStackHeaderConfig>
+      <ScreenStackHeaderConfig
+        backButtonInCustomView={backButtonInCustomView}
+        backgroundColor={
+          headerStyleFlattened.backgroundColor ??
+          (headerBackground != null || headerTransparent
+            ? 'transparent'
+            : colors.card)
+        }
+        backTitle={headerBackTitleVisible ? headerBackTitle : ' '}
+        backTitleFontFamily={backTitleFontFamily}
+        backTitleFontSize={headerBackTitleStyleFlattened.fontSize}
+        blurEffect={headerBlurEffect}
+        color={tintColor}
+        direction={I18nManager.isRTL ? 'rtl' : 'ltr'}
+        disableBackButtonMenu={headerBackButtonMenuEnabled === false}
+        hidden={headerShown === false}
+        hideBackButton={headerBackVisible === false}
+        hideShadow={
+          headerShadowVisible === false ||
+          headerBackground != null ||
+          headerTransparent
+        }
+        largeTitle={headerLargeTitle}
+        largeTitleBackgroundColor={headerLargeStyleFlattened.backgroundColor}
+        largeTitleColor={headerLargeTitleStyleFlattened.color}
+        largeTitleFontFamily={largeTitleFontFamily}
+        largeTitleFontSize={headerLargeTitleStyleFlattened.fontSize}
+        largeTitleFontWeight={headerLargeTitleStyleFlattened.fontWeight}
+        largeTitleHideShadow={headerLargeTitleShadowVisible === false}
+        title={typeof headerTitle === 'string' ? headerTitle : titleText}
+        titleColor={titleColor}
+        titleFontFamily={titleFontFamily}
+        titleFontSize={titleFontSize}
+        titleFontWeight={titleFontWeight}
+        topInsetEnabled={insets.top !== 0}
+        translucent={
+          // This defaults to `true`, so we can't pass `undefined`
+          translucent === true
+        }
+      >
+        {Platform.OS === 'ios' ? (
+          <>
+            {headerLeftElement != null ? (
+              <ScreenStackHeaderLeftView>
+                {headerLeftElement}
+              </ScreenStackHeaderLeftView>
+            ) : null}
+            {headerTitleElement != null ? (
+              <ScreenStackHeaderCenterView>
+                {headerTitleElement}
+              </ScreenStackHeaderCenterView>
+            ) : null}
+          </>
+        ) : (
+          <>
+            {headerLeftElement != null || typeof headerTitle === 'function' ? (
+              <ScreenStackHeaderLeftView>
+                <View style={styles.row}>
+                  {headerLeftElement}
+                  {headerTitleAlign !== 'center' ? (
+                    typeof headerTitle === 'function' ? (
+                      headerTitleElement
+                    ) : (
+                      <HeaderTitle
+                        tintColor={tintColor}
+                        style={headerTitleStyleSupported}
+                      >
+                        {titleText}
+                      </HeaderTitle>
+                    )
+                  ) : null}
+                </View>
+              </ScreenStackHeaderLeftView>
+            ) : null}
+            {headerTitleAlign === 'center' ? (
+              <ScreenStackHeaderCenterView>
+                {typeof headerTitle === 'function' ? (
+                  headerTitleElement
+                ) : (
+                  <HeaderTitle
+                    tintColor={tintColor}
+                    style={headerTitleStyleSupported}
+                  >
+                    {titleText}
+                  </HeaderTitle>
+                )}
+              </ScreenStackHeaderCenterView>
+            ) : null}
+          </>
+        )}
+        {headerBackImageSource !== undefined ? (
+          <ScreenStackHeaderBackButtonImage source={headerBackImageSource} />
+        ) : null}
+        {headerRightElement != null ? (
+          <ScreenStackHeaderRightView>
+            {headerRightElement}
+          </ScreenStackHeaderRightView>
+        ) : null}
+        {hasHeaderSearchBar ? (
+          <ScreenStackHeaderSearchBarView>
+            <SearchBar {...headerSearchBarOptions} />
+          </ScreenStackHeaderSearchBarView>
+        ) : null}
+      </ScreenStackHeaderConfig>
+    </>
   );
 }
 
@@ -231,4 +271,14 @@ const styles = StyleSheet.create({
     flexDirection: 'row',
     alignItems: 'center',
   },
+  translucent: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    zIndex: 1,
+  },
+  background: {
+    overflow: 'hidden',
+  },
 });

package/src/views/NativeStackView.native.tsx

@@ -6,6 +6,8 @@ import {
   SafeAreaProviderCompat,
 } from '@react-navigation/elements';
 import {
+  NavigationContext,
+  NavigationRouteContext,
   ParamListBase,
   Route,
   StackActions,
@@ -13,7 +15,7 @@ import {
   useTheme,
 } from '@react-navigation/native';
 import * as React from 'react';
-import { Platform, PlatformIOSStatic, StyleSheet } from 'react-native';
+import { Platform, StyleSheet, View } from 'react-native';
 import {
   useSafeAreaFrame,
   useSafeAreaInsets,
@@ -40,11 +42,13 @@ const MaybeNestedStack = ({
   options,
   route,
   presentation,
+  headerHeight,
   children,
 }: {
   options: NativeStackNavigationOptions;
   route: Route<string>;
   presentation: Exclude<StackPresentationTypes, 'push'> | 'card';
+  headerHeight: number;
   children: React.ReactNode;
 }) => {
   const { colors } = useTheme();
@@ -83,33 +87,17 @@ const MaybeNestedStack = ({
     </DebugContainer>
   );
 
-  const insets = useSafeAreaInsets();
-  const dimensions = useSafeAreaFrame();
-  // landscape is meaningful only for iPhone
-  const isLandscape =
-    dimensions.width > dimensions.height &&
-    !(Platform as PlatformIOSStatic).isPad &&
-    !(Platform as PlatformIOSStatic).isTVOS;
-  // `modal` and `formSheet` presentations do not take whole screen, so should not take the inset.
-  const isFullScreenModal =
-    presentation !== 'modal' && presentation !== 'formSheet';
-  const topInset = isFullScreenModal && !isLandscape ? insets.top : 0;
-  const headerHeight = getDefaultHeaderHeight(
-    dimensions,
-    !isFullScreenModal,
-    topInset
-  );
-
   if (isHeaderInModal) {
     return (
       <ScreenStack style={styles.container}>
         <Screen enabled style={StyleSheet.absoluteFill}>
-          <HeaderShownContext.Provider value>
-            <HeaderHeightContext.Provider value={headerHeight}>
-              <HeaderConfig {...options} route={route} canGoBack />
-              {content}
-            </HeaderHeightContext.Provider>
-          </HeaderShownContext.Provider>
+          <HeaderConfig
+            {...options}
+            route={route}
+            headerHeight={headerHeight}
+            canGoBack
+          />
+          {content}
         </Screen>
       </ScreenStack>
     );
@@ -142,7 +130,7 @@ const SceneView = ({
     gestureEnabled,
     header,
     headerShown,
-    animationTypeForReplace = 'pop',
+    animationTypeForReplace = 'push',
     animation,
     orientation,
     statusBarAnimation,
@@ -162,14 +150,28 @@ const SceneView = ({
     ? headerShown
     : presentation === 'card' && headerShown !== false;
 
-  const isParentHeaderShown = React.useContext(HeaderShownContext);
   const insets = useSafeAreaInsets();
+  const frame = useSafeAreaFrame();
+
+  // `modal` and `formSheet` presentations do not take whole screen, so should not take the inset.
+  const isModal = presentation === 'modal' || presentation === 'formSheet';
+
+  // Modals are fullscreen in landscape only on iPhone
+  const isIPhone =
+    Platform.OS === 'ios' && !(Platform.isPad && Platform.isTVOS);
+  const isLandscape = frame.width > frame.height;
+
+  const topInset = isModal || (isIPhone && isLandscape) ? 0 : insets.top;
+
+  const isParentHeaderShown = React.useContext(HeaderShownContext);
   const parentHeaderHeight = React.useContext(HeaderHeightContext);
-  const headerHeight = getDefaultHeaderHeight(
-    useSafeAreaFrame(),
-    false,
-    insets.top
-  );
+
+  const defaultHeaderHeight = getDefaultHeaderHeight(frame, isModal, topInset);
+
+  const [customHeaderHeight, setCustomHeaderHeight] =
+    React.useState(defaultHeaderHeight);
+
+  const headerHeight = header ? customHeaderHeight : defaultHeaderHeight;
 
   return (
     <Screen
@@ -204,25 +206,35 @@ const SceneView = ({
           }
         >
           {header !== undefined && headerShown !== false ? (
-            // TODO: expose custom header height
-            header({
-              back: previousDescriptor
-                ? {
-                    title: getHeaderTitle(
-                      previousDescriptor.options,
-                      previousDescriptor.route.name
-                    ),
-                  }
-                : undefined,
-              options,
-              route,
-              navigation,
-            })
+            <NavigationContext.Provider value={navigation}>
+              <NavigationRouteContext.Provider value={route}>
+                <View
+                  onLayout={(e) => {
+                    setCustomHeaderHeight(e.nativeEvent.layout.height);
+                  }}
+                >
+                  {header({
+                    back: previousDescriptor
+                      ? {
+                          title: getHeaderTitle(
+                            previousDescriptor.options,
+                            previousDescriptor.route.name
+                          ),
+                        }
+                      : undefined,
+                    options,
+                    route,
+                    navigation,
+                  })}
+                </View>
+              </NavigationRouteContext.Provider>
+            </NavigationContext.Provider>
           ) : (
             <HeaderConfig
               {...options}
               route={route}
               headerShown={isHeaderInPush}
+              headerHeight={headerHeight}
               canGoBack={index !== 0}
             />
           )}
@@ -230,6 +242,7 @@ const SceneView = ({
             options={options}
             route={route}
             presentation={presentation}
+            headerHeight={headerHeight}
           >
             {render()}
           </MaybeNestedStack>
@@ -246,8 +259,9 @@ type Props = {
 };
 
 function NativeStackViewInner({ state, navigation, descriptors }: Props) {
-  const [nextDismissedKey, setNextDismissedKey] =
-    React.useState<string | null>(null);
+  const [nextDismissedKey, setNextDismissedKey] = React.useState<string | null>(
+    null
+  );
 
   const dismissedRouteName = nextDismissedKey
     ? state.routes.find((route) => route.key === nextDismissedKey)?.name

package/src/views/NativeStackView.tsx

@@ -25,6 +25,11 @@ type Props = {
   descriptors: NativeStackDescriptorMap;
 };
 
+const TRANSPARENT_PRESENTATIONS = [
+  'transparentModal',
+  'containedTransparentModal',
+];
+
 export default function NativeStackView({ state, descriptors }: Props) {
   return (
     <SafeAreaProviderCompat>
@@ -33,9 +38,11 @@ export default function NativeStackView({ state, descriptors }: Props) {
           const isFocused = state.index === i;
           const canGoBack = i !== 0;
           const previousKey = state.routes[i - 1]?.key;
+          const nextKey = state.routes[i + 1]?.key;
           const previousDescriptor = previousKey
             ? descriptors[previousKey]
             : undefined;
+          const nexDescriptor = nextKey ? descriptors[nextKey] : undefined;
           const { options, navigation, render } = descriptors[route.key];
 
           const {
@@ -51,10 +58,13 @@ export default function NativeStackView({ state, descriptors }: Props) {
             headerStyle,
             headerShadowVisible,
             headerTransparent,
-            contentStyle,
             headerBackTitle,
+            presentation,
+            contentStyle,
           } = options;
 
+          const nextPresentation = nexDescriptor?.options.presentation;
+
           return (
             <Screen
               key={route.key}
@@ -115,7 +125,8 @@ export default function NativeStackView({ state, descriptors }: Props) {
                     }
                     headerRight={
                       typeof headerRight === 'function'
-                        ? ({ tintColor }) => headerRight({ tintColor })
+                        ? ({ tintColor }) =>
+                            headerRight({ tintColor, canGoBack })
                         : headerRight
                     }
                     headerTitle={
@@ -143,7 +154,18 @@ export default function NativeStackView({ state, descriptors }: Props) {
               }
               style={[
                 StyleSheet.absoluteFill,
-                { display: isFocused ? 'flex' : 'none' },
+                {
+                  display:
+                    isFocused ||
+                    (nextPresentation != null &&
+                      TRANSPARENT_PRESENTATIONS.includes(nextPresentation))
+                      ? 'flex'
+                      : 'none',
+                },
+                presentation != null &&
+                TRANSPARENT_PRESENTATIONS.includes(presentation)
+                  ? { backgroundColor: 'transparent' }
+                  : null,
               ]}
             >
               <View style={[styles.contentContainer, contentStyle]}>