Skip to main content
Version: 8.x

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.

Comparison with Stack Navigator

The Native Stack navigator uses the native APIs UINavigationController on iOS and Fragment on Android. This means animations and gestures are handled by the platform, resulting in smoother transitions and better performance compared to the JavaScript-based Stack Navigator.

It also exposes native features such as large titles on iOS, form sheets etc., and offers a more native look and feel out of the box.

However, because it relies on native components, it may not support customizations or behaviors not supported by the underlying platforms.

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 install @react-navigation/native-stack@next

Usage​

To use this navigator, import it from @react-navigation/native-stack:

import {
  createNativeStackNavigator,
  createNativeStackScreen,
} from '@react-navigation/native-stack';

const MyStack = createNativeStackNavigator({
  screens: {
    Home: createNativeStackScreen({
      screen: HomeScreen,
    }),
    Profile: createNativeStackScreen({
      screen: ProfileScreen,
    }),
  },
});
info

If you encounter any bugs while using createNativeStackNavigator, please open issues on react-native-screens rather than the react-navigation repository!

API Definition​

Props​

The native stack navigator accepts the common props shared by all navigators.

Options​

The following options can be used to configure the screens in the navigator:

inactiveBehavior​

This controls what should happen when screens become inactive.

It supports the following values:

  • pause: Effects are cleaned up - e.g. timers are cleared, subscriptions are removed, etc. This avoids unnecessary renders when the screen is inactive.
  • unmount: The screen is unmounted when it becomes inactive.
  • none: Screen renders normally.

Defaults to pause.

If you preload a screen, it remains active until it's focused and then unfocused for the first time. If you retain a screen, it stays active and never gets paused or unmounted while retained.

If a screen contains a nested navigator, it won't be unmounted, but paused instead even if inactiveBehavior is set to unmount.

See Inactive screens for more details.

title​

String that can be used as a fallback for headerTitle.

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 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.

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).

Supported values:

  • "auto" (iOS only)
  • "inverted" (iOS only)
  • "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.

Only supported on Android and iOS.

contentStyle​

Style object for the scene content.

animationMatchesGesture​

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.

fullScreenGestureShadowEnabled​

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.

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 push.

Supported values:

  • push: the new screen will perform a push animation.
  • pop: the new screen will perform a pop animation.

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

animation​

How the screen should animate when pushed or popped.

Only supported on Android and iOS.

Supported values:

  • default

    Use the platform default animation.

  • fade

    Fade the screen in or out.

  • fade_from_bottom

    Fade the new screen in from the bottom.