栈

Custom header to use instead of the default header.

This accepts a function that returns a React Element to display as a header. The function receives an object containing the following properties as the argument:

• navigation - The navigation object for the current screen.
• route - The route object for the current screen.
• options - The options for the current screen
• back - Options for the back button, contains an object with a title property to use for back button label.

To set a custom header for all the screens in the navigator, you can specify this option in the screenOptions prop of the navigator.

Note that if you specify a custom header, the native functionality such as large title, search bar etc. won't work.

How the back button displays icon and title.

Supported values:

• "default" - Displays one of the following depending on the available space: previous screen's title, generic title (e.g. 'Back') or no title (only icon).
• "generic" – Displays one of the following depending on the available space: generic title (e.g. 'Back') or no title (only icon).
• "minimal" – Always displays only the icon without a title.

The space-aware behavior is disabled when:

• The iOS version is 13 or lower
• Custom font family or size is set (e.g. with headerBackTitleStyle)
• Back button menu is disabled (e.g. with headerBackButtonMenuEnabled)

In such cases, a static title and icon are always displayed.

Boolean indicating whether to show the menu on longPress of iOS >= 14 back button. Defaults to true.

Function which returns a React Element to render as the background of the header. This is useful for using backgrounds such as an image or a gradient.

Icon to display in the header as the icon in the back button. Defaults to back icon image for the platform:

• A chevron on iOS
• An arrow on Android

Currently only supports image sources.

Title string used by the back button on iOS. Defaults to the previous scene's title, "Back" or arrow icon depending on the available space. See headerBackButtonDisplayMode to read about limitations and customize the behavior.

Use headerBackButtonDisplayMode: "minimal" to hide it.

Style object for header back title. Supported properties:

• fontFamily
• fontSize

Whether the back button is visible in the header. You can use it to show a back button alongside headerLeft if you have specified it.

This will have no effect on the first screen in the stack.

Blur effect for the translucent header. The headerTransparent option needs to be set to true for this to work.

Supported values: extraLight, light, regular, prominent, systemUltraThinMaterial, systemThinMaterial, systemMaterial, systemThickMaterial, systemChromeMaterial, systemUltraThinMaterialLight, systemThinMaterialLight, systemMaterialLight, systemThickMaterialLight, systemChromeMaterialLight, dark, systemUltraThinMaterialDark, systemThinMaterialDark, systemMaterialDark, systemThickMaterialDark, systemChromeMaterialDark

Using both headerBlurEffect and scrollEdgeEffects (>= iOS 26) simultaneously may cause overlapping effects.

Style of the header when a large title is shown. The large title is shown if headerLargeTitleEnabled is true and the edge of any scrollable content reaches the matching edge of the header.

Supported properties:

• backgroundColor

Whether to enable header with large title which collapses to regular header on scroll. Defaults to false.

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.

Whether drop shadow of header is visible when a large title is shown.

Style object for large title in header. Supported properties:

• fontFamily
• fontSize
• fontWeight
• color

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. It receives the following properties in the arguments:

• tintColor - The tint color to apply. Defaults to the theme's primary color.
• canGoBack - Boolean indicating whether there is a screen to go back to.
• label - Label text for the button. Usually the title of the previous screen.
• href - The href to use for the anchor tag on web

Function which returns a React Element to display on the right side of the header. It receives the following properties in the arguments:

• tintColor - The tint color to apply. Defaults to the theme's primary color.
• canGoBack - Boolean indicating whether there is a screen to go back to.

Options to render a native search bar. Search bars are rarely static so normally it is controlled by passing an object to headerSearchBarOptions navigation option in the component's body.

On iOS, you also need to specify contentInsetAdjustmentBehavior="automatic" in your ScrollView, FlatList etc. If you don't have a ScrollView, specify headerTransparent: false.

Supported properties are:

ref

Ref to manipulate the search input imperatively. It contains the following methods:

• focus - focuses the search bar
• blur - removes focus from the search bar
• setText - sets the search bar's content to given value
• clearText - removes any text present in the search bar input field
• cancelSearch - cancel the search and close the search bar
• toggleCancelButton - depending on passed boolean value, hides or shows cancel button (only supported on iOS)

autoCapitalize

Controls whether the text is automatically auto-capitalized as it is entered by the user. Possible values:

• systemDefault
• none
• words
• sentences
• characters

Defaults to systemDefault which is the same as sentences on iOS and none on Android.

autoFocus

Whether to automatically focus search bar when it's shown. Defaults to false.

barTintColor

The search field background color. By default bar tint color is translucent.

tintColor

The color for the cursor caret and cancel button text.

cancelButtonText

The text to be used instead of default Cancel button text.

Deprecated starting from iOS 26.

disableBackButtonOverride

Whether the back button should close search bar's text input or not. Defaults to false.

hideNavigationBar

Boolean indicating whether to hide the navigation bar during searching.

If left unset, system default is used.

hideWhenScrolling

Boolean indicating whether to hide the search bar when scrolling. Defaults to true.

inputType

The type of the input. Defaults to "text".

Supported values: "text", "phone", "number", "email"

obscureBackground

Boolean indicating whether to obscure the underlying content with semi-transparent overlay.

If left unset, system default is used.

placement

Controls preferred placement of the search bar. Defaults to automatic.

Supported values: automatic, stacked, inline, integrated, integratedButton, integratedCentered

allowToolbarIntegration

Boolean indicating whether the system can place the search bar among other toolbar items on iPhone.

Set this prop to false to prevent the search bar from appearing in the toolbar when placement is automatic, integrated, integratedButton or integratedCentered.

Defaults to true. If placement is set to stacked, the value of this prop will be overridden with false.

Only supported on iOS, starting from iOS 26.

placeholder

Text displayed when search field is empty.

textColor

The color of the text in the search field.

hintTextColor

The color of the hint text in the search field.

headerIconColor

The color of the search and close icons shown in the header

shouldShowHintSearchIcon

Whether to show the search hint icon when search bar is focused. Defaults to true.

onBlur

A callback that gets called when search bar has lost focus.

onCancelButtonPress

A callback that gets called when the cancel button is pressed.

onSearchButtonPress

A callback that gets called when the search button is pressed.

const [search, setSearch] = React.useState('');

React.useLayoutEffect(() => {
  navigation.setOptions({
    headerSearchBarOptions: {
      onSearchButtonPress: (event) => setSearch(event?.nativeEvent?.text),
    },
  });
}, [navigation]);

onChangeText

A callback that gets called when the text changes. It receives the current text value of the search bar.

headerShown

Whether to show the header. The header is shown by default. Setting this to false hides the header.

Whether to hide the elevation shadow (Android) or the bottom border (iOS) on the header.

Whether to show the header. The header is shown by default. Setting this to false hides the header.

Style object for header. Supported properties:

• backgroundColor

Tint color for the header. Changes the color of back button and title.

String or a function that returns a React Element to be used by the header. Defaults to title or name of the screen.

When a function is passed, it receives tintColor andchildren in the options object as an argument. The title string is passed in children.

Note that if you render a custom element by passing a function, animations for the title won't work.

How to align the header title. Possible values:

• left
• center

Defaults to left on platforms other than iOS.

Not supported on iOS. It's always center on iOS and cannot be changed.

Style object for header title. Supported properties:

• fontFamily
• fontSize
• fontWeight
• color

Boolean indicating whether the navigation bar is translucent.

Defaults to false. Setting this to true makes the header absolutely positioned - so that the header floats over the screen so that it overlaps the content underneath, and changes the background color to transparent unless specified in headerStyle.

This is useful if you want to render a semi-transparent header or a blurred background.

Note that if you don't want your content to appear under the header, you need to manually add a top margin to your content. React Navigation won't do it automatically.

To get the height of the header, you can use HeaderHeightContext with React's Context API or useHeaderHeight.

String that can be used as a fallback for headerTitle.

Which edges of the native header apply window insets (e.g. statusbar inset) on Android.

The native header applies insets to every edge by default. Setting an edge to false removes the inset for that edge:

unstable_headerInsets: {
  top: false,
  bottom: false,
}

Supported edges are top, left, right, and bottom.

Disabling an inset also disables it for nested headers. A nested header cannot re-enable an inset disabled by a parent header.

This API may change in a minor release.

This option is experimental and may change in a minor release.

Function which returns an array of items to display as on the left side of the header. This will override headerLeft if both are specified. It receives the following properties in the arguments:

• tintColor - The tint color to apply. Defaults to the theme's primary color.
• canGoBack - Boolean indicating whether there is a screen to go back to.

See Header items for more information.

This option is experimental and may change in a minor release.

Function which returns an array of items to display as on the right side of the header. This will override headerRight if both are specified. It receives the following properties in the arguments:

• tintColor - The tint color to apply. Defaults to the theme's primary color.
• canGoBack - Boolean indicating whether there is a screen to go back to.

See Header items for more information.

How the screen should animate when pushed or popped.

Supported values: default, fade, fade_from_bottom, flip, simple_push, slide_from_bottom, slide_from_right, slide_from_left, none

Changes the duration (in milliseconds) of slide_from_bottom, fade_from_bottom, fade and simple_push transitions on iOS. Defaults to 350.

For screens with default and flip transitions, and, as of now, for screens with presentation set to modal, formSheet, pageSheet (regardless of transition), the duration isn't customizable.

Whether the gesture to dismiss should use animation provided to animation prop. Defaults to false.

Doesn't affect the behavior of screens presented modally.

The type of animation to use when this screen replaces another screen. Defaults to push.

Supported values: push, pop

This can be useful to provide appropriate animations, such as push for login and pop for logout.

Boolean indicating whether the home indicator should prefer to stay hidden. Defaults to false.

Style object for the scene content.

Boolean indicating whether to prevent inactive screens from re-rendering. Defaults to false. Defaults to true when enableFreeze() from react-native-screens package is run at the top of the application.

Only supported on iOS and Android.

Whether the gesture to dismiss should work on the whole screen. Using gesture to dismiss with this option results in the same transition animation as simple_push. This behavior can be changed by setting customAnimationOnGesture prop. Achieving the default iOS animation isn't possible due to platform limitations. Defaults to false.

Doesn't affect the behavior of screens presented modally.

Whether the full screen dismiss gesture has shadow under view during transition. Defaults to true.

This does not affect the behavior of transitions that don't use gestures enabled by fullScreenGestureEnabled prop.

Sets the direction in which you should swipe to dismiss the screen.

Supported values: vertical, horizontal

When using vertical option, options fullScreenGestureEnabled: true, customAnimationOnGesture: true and animation: 'slide_from_bottom' are set by default.

Whether you can use gestures to dismiss this screen. Defaults to true.

This option is deprecated and will be removed in a future release (for apps targeting Android SDK 35 or above edge-to-edge mode is enabled by default and it is expected that the edge-to-edge will be enforced in future SDKs, see here for more information).

Sets the navigation bar color. Defaults to initial status bar color.

Boolean indicating whether the navigation bar should be hidden. Defaults to false.

The display orientation to use for the screen.

Supported values: default, all, portrait, portrait_up, portrait_down, landscape, landscape_left, landscape_right

How should the screen be presented.

Supported values: card, modal, containedModal, fullScreenModal, transparentModal, containedTransparentModal, formSheet

Configures the scroll edge effect for the content ScrollView (the ScrollView that is present in first descendants chain of the Screen). Depending on values set, it will blur the scrolling content below certain UI elements (e.g. header items, search bar) for the specified edge of the ScrollView. When set in nested containers, i.e. Native Stack inside Native Bottom Tabs, or the other way around, the ScrollView will use only the innermost one's config.

Edge effects can be configured for each edge separately. The following values are currently supported:

• automatic - the automatic scroll edge effect style,
• hard - a scroll edge effect with a hard cutoff and dividing line,
• soft - a soft-edged scroll edge effect,
• hidden - no scroll edge effect.

Defaults to automatic for each edge.

Using both blurEffect and scrollEdgeEffects (>= iOS 26) simultaneously may cause overlapping effects.

Only supported on iOS, starting from iOS 26.

Describes heights where a sheet can rest.

Supported values: 'fitToContents' or an array of fractions (e.g. [0.25, 0.5, 0.75]). The array must be sorted in ascending order. This invariant is verified only in development mode, where violation results in an error. Android is limited to 3 detents.

Defaults to [1.0].

See Configuring sheet sizes for usage examples.

The corner radius of the sheet. If set to a non-negative value it will use the provided radius, otherwise the system default is used.

Integer value describing elevation of the sheet, impacting shadow on the top edge.

Not dynamic - changing it after the component is rendered won't have an effect.

Defaults to 24.

Whether the sheet should expand to a larger detent when scrolling.

The ScrollView must be reachable by following the first child view at each level of the view hierarchy from the screen component.

Defaults to true.

See Scroll behavior for more details.

Whether the sheet shows a grabber handle at the top.

Defaults to false.

Index of the detent the sheet should expand to after being opened. If the specified index is out of bounds of the sheetAllowedDetents array, an error will be thrown in development mode and the value will be reset to the default in production.

Can also be set to 'last' to open at the largest detent.

Defaults to 0.

See Configuring sheet sizes for usage examples.

The largest detent index for which the view underneath won't be dimmed.

Can be set to a number (index into sheetAllowedDetents), 'none' (always dim), or 'last' (never dim).

Defaults to 'none'.

See Controlling dimming for usage examples.

Whether the default native animation should be used when the sheet's content size changes (specifically when using fitToContents).

Set to false to implement custom resizing animations.

Defaults to true.

Whether the sheet content should be rendered behind the status bar or display cutouts.

When true, detent ratios in sheetAllowedDetents are measured relative to the full stack height. When false, they are measured relative to the adjusted height (excluding the top inset).

Defaults to false.

Sets the status bar animation (similar to the StatusBar component). Defaults to fade on iOS and none on Android.

Supported values: "fade", "none", "slide"

On Android, setting either fade or slide will set the transition of status bar color. On iOS, this option applies to the appearance animation of the status bar.

Requires setting View controller-based status bar appearance -> YES (or removing the config) in your Info.plist file.

This option is deprecated and will be removed in a future release (for apps targeting Android SDK 35 or above edge-to-edge mode is enabled by default and it is expected that the edge-to-edge will be enforced in future SDKs, see here for more information).

Sets the background color of the status bar (similar to the StatusBar component).

Whether the status bar should be hidden on this screen.

Requires setting View controller-based status bar appearance -> YES (or removing the config) in your Info.plist file.

Sets the status bar color (similar to the StatusBar component).

Supported values: "auto", "inverted", "dark", "light"

Defaults to auto on iOS and light on Android.

Requires setting View controller-based status bar appearance -> YES (or removing the config) in your Info.plist file.

This option is deprecated and will be removed in a future release (for apps targeting Android SDK 35 or above edge-to-edge mode is enabled by default and it is expected that the edge-to-edge will be enforced in future SDKs, see here for more information).

Sets the translucency of the status bar (similar to the StatusBar component). Defaults to false.

Accessibility label for the tab button. This is read by the screen reader when the user taps the tab. It's recommended to set this if you don't have a label for the tab.

Background color for the active tab.

Color for the icon and label in the active tab.

Function which returns a React Element to use as background for the tab bar. You could render an image, a gradient, blur view etc.:

import { BlurView } from 'expo-blur';
import { StyleSheet } from 'react-native';
import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';

// ...

createBottomTabNavigator({
  screenOptions: {
    tabBarStyle: { position: 'absolute' },
    tabBarBackground: () => (
      <BlurView tint="light" intensity={100} style={StyleSheet.absoluteFill} />
    ),
  },
  screens: {
    // ...
  },
});

import { BlurView } from 'expo-blur';
import { StyleSheet } from 'react-native';

// ...

<Tab.Navigator
  screenOptions={{
    tabBarStyle: { position: 'absolute' },
    tabBarBackground: () => (
      <BlurView tint="light" intensity={100} style={StyleSheet.absoluteFill} />
    ),
  }}
>

When using BlurView, make sure to set position: 'absolute' in tabBarStyle as well. You'd also need to use useBottomTabBarHeight to add bottom padding to your content.

Text to show in a badge on the tab icon. Accepts a string or a number.

Style for the badge on the tab icon. You can specify a background color or text color here.

Function which returns a React element to render as the tab bar button. It wraps the icon and label. Renders PlatformPressable by default.

You can specify a custom implementation here:

tabBarButton: (props) => <TouchableOpacity {...props} />;

ID to locate this tab button in tests.

Whether the tab bar is hidden when the keyboard opens. Defaults to false.

Function that given { focused: boolean, color: string, size: number } returns a React.Node, to display in the tab bar.

Style object for the tab icon.

Background color for the inactive tabs.

Color for the icon and label in the inactive tabs.

Style object for the tab item container.

Title string of a tab displayed in the tab bar or a function that given { focused: boolean, color: string } returns a React.Node, to display in tab bar. When undefined, scene title is used. To hide, see tabBarShowLabel.

Whether the label is shown below the icon or beside the icon. By default, the position is chosen automatically based on device width.

• below-icon

  The label is shown below the icon (typical for devices with smaller widths such as phones)

• beside-icon

  The label is shown next to the icon (typical for larger devices such as tablets)

Style object for the tab label.

Position of the tab bar. Available values are:

• bottom (Default)
• top
• left
• right

When the tab bar is positioned on the left or right, it is styled as a sidebar. This can be useful when you want to show a sidebar on larger screens and a bottom tab bar on smaller screens:

You can also render a compact sidebar by placing the label below the icon. This is only supported when the tabBarVariant is set to material:

Whether the tab label should be visible. Defaults to true.

Style object for the tab bar. You can configure styles such as background color here.

To show your screen under the tab bar, you can set the position style to absolute:

createBottomTabNavigator({
  screenOptions: {
    tabBarStyle: { position: 'absolute' },
  },
  screens: {
    // ...
  },
});

<Tab.Navigator
  screenOptions={{
    tabBarStyle: { position: 'absolute' },
  }}
>

You also might need to add a bottom margin to your content if you have an absolutely positioned tab bar. React Navigation won't do it automatically. See useBottomTabBarHeight for more details.

Variant of the tab bar. Available values are:

• uikit (Default) - The tab bar will be styled according to the iOS UIKit guidelines.
• material - The tab bar will be styled according to the Material Design guidelines.

The material variant is currently only supported when the tabBarPosition is set to left or right.