Native Stack Navigator
Native Stack Navigator provides a way for your app to transition between screens where each new screen is placed on top of a stack.
This navigator uses the native APIs UINavigationController
on iOS and Fragment
on Android so that navigation built with createNativeStackNavigator
will behave exactly the same and have the same performance characteristics as apps built natively on top of those APIs. It also offers basic Web support using react-native-web
.
One thing to keep in mind is that while @react-navigation/native-stack
offers native performance and exposes native features such as large title on iOS etc., it may not be as customizable as @react-navigation/stack
depending on your needs. So if you need more customization than what's possible in this navigator, consider using @react-navigation/stack
instead - which is a more customizable JavaScript based implementation.
Installationβ
To use this navigator, ensure that you have @react-navigation/native
and its dependencies (follow this guide), then install @react-navigation/native-stack
:
- npm
- Yarn
- pnpm
npm install @react-navigation/native-stack
yarn add @react-navigation/native-stack
pnpm add @react-navigation/native-stack
API Definitionβ
π‘ If you encounter any bugs while using
createNativeStackNavigator
, please open issues onreact-native-screens
rather than thereact-navigation
repository!
To use this navigator, import it from @react-navigation/native-stack
:
import { createNativeStackNavigator } from '@react-navigation/native-stack';
const Stack = createNativeStackNavigator();
function MyStack() {
return (
<Stack.Navigator>
<Stack.Screen name="Home" component={Home} />
<Stack.Screen name="Notifications" component={Notifications} />
<Stack.Screen name="Profile" component={Profile} />
<Stack.Screen name="Settings" component={Settings} />
</Stack.Navigator>
);
}
Propsβ
The Stack.Navigator
component accepts following props:
id
β
Optional unique ID for the navigator. This can be used with navigation.getParent
to refer to this navigator in a child navigator.
initialRouteName
β
The name of the route to render on first load of the navigator.
screenOptions
β
Default options to use for the screens in the navigator.
Optionsβ
The following options can be used to configure the screens in the navigator:
title
β
String that can be used as a fallback for headerTitle
.
headerBackButtonMenuEnabled
β
Boolean indicating whether to show the menu on longPress of iOS >= 14 back button. Defaults to true
.
Requires react-native-screens
version >=3.3.0.
Only supported on iOS.
headerBackVisible
β
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.
headerBackTitle
β
Title string used by the back button on iOS. Defaults to the previous scene's title, or "Back" if there's not enough space. Use headerBackTitleVisible: false
to hide it.
Only supported on iOS.
headerBackTitleVisible
β
Whether the back button title should be visible or not.
Only supported on iOS.
headerBackTitleStyle
β
Style object for header back title. Supported properties:
fontFamily
fontSize
Only supported on iOS.
headerBackImageSource
β
Image 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
headerLargeStyle
β
Style of the header when a large title is shown. The large title is shown if headerLargeTitle
is true
and the edge of any scrollable content reaches the matching edge of the header.
Supported properties:
- backgroundColor
Only supported on iOS.
headerLargeTitle
β
Whether to enable header with large title which collapses to regular header on scroll.
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.
headerLargeTitleShadowVisible
β
Whether drop shadow of header is visible when a large title is shown.
headerLargeTitleStyle
β
Style object for large title in header. Supported properties:
fontFamily
fontSize
fontWeight
color
Only supported on iOS.
headerShown
β
Whether to show the header. The header is shown by default. Setting this to false
hides the header.
headerStyle
β
Style object for header. Supported properties:
backgroundColor
headerShadowVisible
β
Whether to hide the elevation shadow (Android) or the bottom border (iOS) on the header.
headerTransparent
β
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
.
headerBlurEffect
β
Blur effect for the translucent header. The headerTransparent
option needs to be set to true
for this to work.
Supported values:
extraLight
light
dark
regular
prominent
systemUltraThinMaterial
systemThinMaterial
systemMaterial
systemThickMaterial
systemChromeMaterial
systemUltraThinMaterialLight
systemThinMaterialLight
systemMaterialLight
systemThickMaterialLight
systemChromeMaterialLight
systemUltraThinMaterialDark
systemThinMaterialDark
systemMaterialDark
systemThickMaterialDark
systemChromeMaterialDark
Only supported on iOS.
headerBackground
β
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.
headerTintColor
β
Tint color for the header. Changes the color of back button and title.
headerLeft
β
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.
headerRight
β
Function which returns a React Element to display on the right side of the header.
headerTitle
β
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.
headerTitleAlign
β
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.
headerTitleStyle
β
Style object for header title. Supported properties:
fontFamily
fontSize
fontWeight
color
headerSearchBarOptions
β
Options to render a native search bar on iOS. Search bars are rarely static so normally it is controlled by passing an object to headerSearchBarOptions
navigation option in the component's body. You also need to specify contentInsetAdjustmentBehavior="automatic"
in your ScrollView
, FlatList
etc. If you don't have a ScrollView
, specify headerTransparent: false
.
Only supported on iOS and Android.
Example:
React.useLayoutEffect(() => {
navigation.setOptions({
headerSearchBarOptions: {
// search bar options
},
});
}, [navigation]);
Supported properties are described below.
autoCapitalize
β
Controls whether the text is automatically auto-capitalized as it is entered by the user. Possible values:
none
words
sentences
characters
Defaults to sentences
.
autoFocus
β
Whether to automatically focus search bar when it's shown. Defaults to false
.
Only supported on Android.
barTintColor
β
The search field background color. By default bar tint color is translucent.
Only supported on iOS.
tintColor
β
The color for the cursor caret and cancel button text.
Only supported on iOS.
cancelButtonText
β
The text to be used instead of default Cancel
button text.
Only supported on iOS.
disableBackButtonOverride
β
Whether the back button should close search bar's text input or not. Defaults to false
.
Only supported on Android.
hideNavigationBar
β
Boolean indicating whether to hide the navigation bar during searching. Defaults to true
.
Only supported on iOS.
hideWhenScrolling
β
Boolean indicating whether to hide the search bar when scrolling. Defaults to true
.
Only supported on iOS.
inputType
β
The type of the input. Defaults to "text"
.
Supported values:
"text"
"phone"
"number"
"email"
Only supported on Android.
obscureBackground
β
Boolean indicating whether to obscure the underlying content with semi-transparent overlay. Defaults to true
.
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.
Only supported on Android.
headerIconColor
β
The color of the search and close icons shown in the header
Only supported on Android.
shouldShowHintSearchIcon
β
Whether to show the search hint icon when search bar is focused. Defaults to true
.
Only supported on Android.
onBlur
β
A callback that gets called when search bar has lost focus.
onCancelButtonPress
β
A callback that gets called when the cancel button is pressed.
onChangeText
β
A callback that gets called when the text changes. It receives the current text value of the search bar.
Example:
const [search, setSearch] = React.useState('');
React.useLayoutEffect(() => {
navigation.setOptions({
headerSearchBarOptions: {
onChangeText: (event) => setSearch(event.nativeEvent.text),
},
});
}, [navigation]);
header
β
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 screenback
- Options for the back button, contains an object with atitle
property to use for back button label.
Example:
import { getHeaderTitle } from '@react-navigation/elements';
// ..
header: ({ navigation, route, options, back }) => {
const title = getHeaderTitle(options, route.name);
return (
<MyHeader
title={title}
leftButton={
back ? <MyBackButton onPress={navigation.goBack} /> : undefined
}
style={options.headerStyle}
/>
);
};
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.
statusBarAnimation
β
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 appereance animation of the status bar.
Requires setting View controller-based status bar appearance -> YES
(or removing the config) in your Info.plist
file.
Only supported on Android and iOS.
statusBarHidden
β
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.
Only supported on Android and iOS.
statusBarStyle
β
Sets the status bar color (similar to the StatusBar
component). Defaults to auto
.
Supported values:
"auto"
"inverted"
(iOS only)"dark"
"light"
Requires setting View controller-based status bar appearance -> YES
(or removing the config) in your Info.plist
file.
Only supported on Android and iOS.
statusBarColor
β
Sets the status bar color (similar to the StatusBar
component). Defaults to initial status bar color.
Only supported on Android.
statusBarTranslucent
β
Sets the translucency of the status bar (similar to the StatusBar
component). Defaults to false
.
Only supported on Android.
contentStyle
β
Style object for the scene content.
customAnimationOnGesture
β
Whether the gesture to dismiss should use animation provided to animation
prop. Defaults to false
.
Doesn't affect the behavior of screens presented modally.
Only supported on iOS.
fullScreenGestureEnabled
β
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.
Only supported on iOS.
gestureEnabled
β
Whether you can use gestures to dismiss this screen. Defaults to true
. Only supported on iOS.
animationTypeForReplace
β
The type of animation to use when this screen replaces another screen. Defaults to pop
.
Supported values:
push
: the new screen will perform push animation.pop
: the new screen will perform pop animation.