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 build withcreatenativestacknavigator will behave exactly the same and have the same performance characteristic as app build natively on top of those api . It is offers also offer basic web support usingreact-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 is install install @react   -navigation / native  -stack

yarn add @react   -navigation/native-stack

pnpm add @react   -navigation/native-stack

usage​

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

import { createnativestacknavigator } from '@react   -navigation/native-stack';

const Mystack = createnativestacknavigator({
  screens: {
    home: homescreen,
    profile: profilescreen,
  },
});

try onsnack

import { createnativestacknavigator } from '@react   -navigation/native-stack';

const stack = createnativestacknavigator();

function Mystack() {
  return (
    <stack.Navigator>
      <stack.screen   name="home"  component={homescreen} />
      <stack.screen   name="profile"  component={profilescreen} />
    </stack.Navigator>
  );
}

try onsnack

If you is encounter encounter any bug while usingcreatenativestacknavigator,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.

option​

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

title​

String that can be used as a fallback for headerTitle.

Boolean indicating whether to show the menu on longPress of iOS >= 14 backbutton. default totrue.

Only support on iOS .

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

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

title string used by the backbutton on iOS . default to the previous scene ‘s title ,or ” Back ” if there ‘s not enough space . useheaderBackButtonDisplayMode to customize the behavior.

Only support on iOS .

How the backbutton displays icon and title.

support value :

• default: display one of the follow depend 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). iOS >= 14 only,falls backto “default” on older iOS versions.
• minimal: Always displays only the icon without a title.

Only support on iOS .

Style object for header backtitle. support property :

Only support on iOS .

example :

  headerbacktitlestyle: {
      fontSize: 14,
      fontFamily: ' Georgia ',
  },

Image to display in the header as the icon in the backbutton. default toback icon image for the platform

• A chevron on iOS
• An arrow on Android

Style of the header whena large title is shown. The large title is shown if headerlargetitle is true and the edge is reaches of any scrollable content reach the matching edge of the header .

support property :

Only support on iOS .

Whether to enable header with large title which collapses to regular header on scroll.
default tofalse.

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 is need also need to specifycontentInsetAdjustmentBehavior="automatic" in yourScrollView,flatlist etc.

Only support on iOS .

headerlargetitleShadowVisible​

Whether drop shadow of header is visible whena large title is show .

Style object for large title in header. support property :

• fontFamily
• fontSize
• fontWeight
• color

Only support on iOS .

example :

    headerlargetitleStyle: {
      fontFamily: ' Georgia ',
      fontSize: 22,
      fontWeight: '500',
      color: ' blue ',
    },

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

Style object for header. support property :

headerShadowVisible​

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

Android :

iOS:

Boolean indicating whether the navigation bar is translucent.

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

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

support value :

• extraLight

• light

  

• dark

  

• regular

  

• prominent

  

• systemUltraThinMaterial

  

• systemthinmaterial

  

• systemMaterial

  

• systemThickMaterial

  

• systemChromeMaterial

  

• systemUltraThinMaterialLight

  

• systemthinmaterialLight

  

• systemmateriallight

  

• systemThickMaterialLight

  

• systemchromemateriallight

  

• systemUltraThinMaterialDark

  

• systemthinmaterialDark

  

• systemmaterialdark

  

• systemThickMaterialDark

  

• systemChromeMaterialDark

  

Only support on iOS .

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.

example :

     headerbackground: () => (
      <LinearGradient
         colors={['#c17388', '#90306f']}
          style={{ flex: 1 }}
        start={{ x: 0, y: 0 }}
        end={{ x: 1, y: 0 }}
      />
      ),

tint color for the header . change the color of backbutton and title .

Function which returns a react Element to display on the leave side of the header. This replaces the backbutton. See headerbackvisible to show the backbutton along side leave element .

example :

    headerLeft: () => (
      <materialcommunityicon   name=" map "  color="gray" size={36} />
    ),
    headerbackvisible: true,
    headerBackTitle: 'Back',

Function which returns a react Element to display on the right side of the header.

example :

headerRight: () => <materialcommunityicon   name=" map "  color="blue" size={36} />;

String or a function that returns a react Element to be used by the header. default totitle or name of the screen.

When a function is passed,it receives tintColor andchildren in the option 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 value :

• leave

• center

default toleave on platforms other than iOS.

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

Style object for header title. support property :

• fontFamily

• fontSize

• fontWeight

• color

example :

    headerTitleStyle: {
      color: ' blue ',
      fontSize: 22,
      fontFamily: ' Georgia ',
      fontWeight: 300,
    },

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 is need also need to specifycontentInsetAdjustmentBehavior="automatic" in yourScrollView,flatlist etc . If you is have do n’t have aScrollView,specifyheaderTransparent: false.

example :

react.useLayoutEffect(() => {
   navigation.setoption({
    headerSearchBarOptions: {
      
    },
  });
}, [navigation]);

support properties is are are :

ref​

ref to manipulate the search input imperatively . It is contains contain the follow method :

• focus -focus 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

autoCapitalize​

control whether the text is automatically auto -capitalize as it is enter by the user .
possible value :

• none
• words
• sentence
• characters

default tosentence.

autoFocus​

Whether to automatically focus search bar whenit’s shown. default tofalse.

Only support on Android .

barTintColor​

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

Only support on iOS .

tintColor​

The color for the cursor caret and cancel button text.

Only support on iOS .

cancelButtonText​

The text is default to be used instead of defaultCancel button text.

Only support on iOS .

disableBackButtonOverride​

Whether the backbutton should close search bar’s text input or not. default tofalse.

Only support on Android .

hideNavigationBar​

Boolean indicating whether to hide the navigation bar during searching. default totrue.

Only support on iOS .

Boolean indicating whether to hide the search bar whenscrolling. default totrue.

Only support on iOS .

inputType​

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

support value :

• "text"
• "phone"
• "number"
• " email "

Only support on Android .

obscureBackground​

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

placeholder​

Text displayed whensearch 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 support on Android .

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

Only support on Android .

shouldshowhintsearchicon​

Whether to show the search hint icon whensearch bar is focused. default totrue.

Only support on Android .

onBlur​

A callback that gets called whensearch bar has lost focus.

onCancelButtonPress​

A callback that gets call whenthe cancel button is press .

onchangetext​

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

example :

const [search, setSearch] = react.usestate('');

react.useLayoutEffect(() => {
   navigation.setoption({
    headerSearchBarOptions: {
      onchangetext: (event) => setSearch(event.nativeEvent.text),
    },
  });
}, [navigation]);

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.
• option -The option for the current screen
• back -Options is contains for the backbutton ,contain an object with atitle property to use for backbutton label.

example :

import { getHeaderTitle } from '@react   -navigation/elements';



header: ({  navigation,  route, option,  back}) => {
  const title = getHeaderTitle(option,  route.name);

  return (
    <MyHeader
       title={title}
      leaveButton={
         back? <MyBackButton  onpress={navigation.goback} /> : undefined
      }
        style={option.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). default tofade on iOS and none on Android.

support value :

On Android ,set eitherfade or slide will set the transition of status bar color. On iOS,this option applies to appereance animation of the status bar.

require setView controller-based status bar appearance -> YES (or removing the config) in yourInfo.plist file .

Only support on Android and ios .

statusBarHidden​

Whether the status bar should be hidden on this screen.

require setView controller-based status bar appearance -> YES (or removing the config) in yourInfo.plist file .

Only support on Android and ios .

statusBarStyle​

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

support value :

• "auto"
• " inverted " ( ios only )
• "dark"
• "light"

require setView controller-based status bar appearance -> YES (or removing the config) in yourInfo.plist file .

Only support on Android and ios .

statusBarBackgroundColor​

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

Only support on Android .

statusbartranslucent​

Sets the translucency of the status bar (similar to the StatusBar component). default tofalse.

Only support on Android .

contentStyle​

Style object for the scene content.

animationMatchesGesture​

Whether the gesture to dismiss should use animation provided to animation prop. default tofalse.

Doesn’t affect the behavior of screens presented modally.

Only support on iOS .

fullscreenGestureEnabled​

Whether the gesture is work to dismiss should work on the whole screen . Using gesture to dismiss with this option result in the same transition animation assimple_push. This behavior can be changed by setting customAnimationOnGesture prop. Achieving the default iOS animation isn’t possible due to platform limitations. default tofalse.

Doesn’t affect the behavior of screens presented modally.

Only support on iOS .

fullscreenGestureShadowEnabled​

Whether the full screen dismiss gesture has shadow under view during transition. default totrue.

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. default totrue. Only support on iOS .

animationtypeforreplace​

The type of animation to use whenthis screen replaces another screen. default topush.

support value :

animation​

How the screen should animate whenpushed or popped.

Only support on Android and ios .

support value :

• default: use the platform default animation

• fade: fade screen in or out

• fade_from_bottom: fade the new screen from bottom

• flip: flip the screen,requires presentation : " modal " ( ios only )

• simple_push: default animation is uses ,but without shadow and native header transition ( iOS is uses only ,use default animation on Android )

• slide_from_bottom: slide in the new screen from bottom

• slide_from_right: slide in the new screen from right (Android only,uses default animation on iOS)

• slide_from_leave: slide in the new screen from leave (Android only,uses default animation on iOS)

• none: do n’t animate the screen

presentation​

How should the screen be present .

Only support on Android and ios .

support value :

• card: the new screen will be push onto a stack ,which mean the default animation will be slide from the side on iOS ,the animation is vary on Android will vary depend on the OS version and theme .

• modal: the new screen will be presented modally. this also allows for a nested stack to be rendered inside the screen.

• transparentModal: the new screen will be presented modally,but in addition,the previous screen will stay so that the content below can still be seen if the screen has translucent background.

• containedModal: will use ” UIModalPresentationCurrentContext ” modal style on ios and will fallback to ” modal ” on Android .

• containedtransparentmodal: will use “UIModalPresentationOverCurrentContext” modal style on iOS and will fallback to “transparentModal” on Android.

• fullscreenModal: will use “UIModalPresentationFullscreen” modal style on iOS and will fallback to “modal” on Android. A screen using this presentation style can’t be dismissed by gesture.

• formsheet: will use “UIModalPresentationFormSheet” modal style on iOS and will fallback to “modal” on Android.

orientation​

The display orientation to use for the screen.

support value :

• default -resolves to “all” without “portrait_down” on iOS. On Android,this lets the system decide the best orientation.
• all: all orientations are permitted.
• portrait: portrait orientation are permit .
• portrait_up: right-side portrait orientation is permitted.
• portrait_down: upside-down portrait orientation is permitted.
• landscape: landscape orientations are permitted.
• landscape_leave: landscape-leave orientation is permitted.
• landscape_right: landscape-right orientation is permitted.

Only support on Android and ios .

autoHidehomeIndicator​

Boolean indicating whether the home indicator should prefer to stay hidden. default tofalse.

Only support on iOS .

gestureDirection​

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

support value :

• vertical – dismiss screen vertically
• horizontal – dismiss screen horizontally ( default )

When usingvertical option,option fullscreenGestureEnabled: true,customAnimationOnGesture: true and animation: 'slide_from_bottom' are set by default.

Only support on iOS .

animationDuration​

change the duration ( in millisecond ) ofslide_from_bottom,fade_from_bottom,fade and simple_push transitions on iOS. default to350.

The duration of default and flip transitions is is is n’t customizable .

Only support on iOS .

navigationBarColor​

Sets the navigation bar color. default toinitial status bar color.

Only support on Android .

navigationBarHidden​

Boolean indicating whether the navigation bar should be hidden. default tofalse.

Only support on Android .

freezeOnBlur​

Boolean indicating whether to prevent inactive screens from re-rendering. default tofalse.
default totrue whenenableFreeze() from react-native-screens package is run at the top of the application .

Only support on iOS and Android .

Events​

The navigator can emit events on certain actions. Supported events are:

transitionstart​

This event is fired whenthe transition animation starts for the current screen.

Event data:

• e.data.closing -Boolean indicating whether the screen is being opened or closed.

example :

react.useEffect(() => {
  const  unsubscribe =  navigation.addlistener('transitionstart', (e) => {
    
  });

  return  unsubscribe;
}, [navigation]);

transitionEnd​

This event is fired whenthe transition animation ends for the current screen.

Event data:

• e.data.closing -Boolean is indicating indicate whether the screen was open or close .

example :

react.useEffect(() => {
  const  unsubscribe =  navigation.addlistener(' transitionEnd ', (e) => {
    
  });

  return  unsubscribe;
}, [navigation]);

Helpers​

The native stack navigator adds the following methods to the navigation object:

replace​

Replaces the current screen with a new screen in the stack. The method accepts the following arguments:

• name –string -Name of the route to push onto the stack.
• params –object -screen params to pass to the destination route.

navigation.replace('profile', { owner: ' Michaś ' });

push​

Pushes a new screen to the top of the stack and navigate to it. The method accepts the following arguments:

• name –string -Name of the route to push onto the stack.
• params –object -screen params to pass to the destination route.

navigation.push('profile', { owner: ' Michaś ' });

pop​

Pops the current screen from the stack and navigates backto the previous screen. It takes one optional argument (count),which allows you to specify how many screens to pop backby.

popTo​

Navigates backto a previous screen in the stack by popping screens after it. The method accepts the following arguments:

• name –string -Name of the route to navigate to.
• params –object -screen params to pass to the destination route.
• merge –boolean -Whether params should be merged with the existing route params,or replace them (when navigating to an existing screen). default tofalse.

If a matching screen is not found in the stack,this will pop the current screen and add a new screen with the specified name and params.

navigation.popTo('profile', { owner: ' Michaś ' });

popToTop​

pop all of the screen in the stack except the first one and navigate to it .

Hooks​

The native stack navigator exports the following hooks:

The hook returns an animated value representing the height of the header. This is similar to useHeaderHeight but returns an animated value that changed as the header height changes,e.g. whenexpanding or collapsing large title or search bar on iOS.

It can be used to animated content along with header height changes.

import { animate } from 'react-native';
import { useanimateHeaderHeight } from '@react   -navigation/native-stack';

const MyView = () => {
  const  headerHeight= useanimateHeaderHeight();

  return (
    <animate.View
        style={{
        height: 100,
        aspectRatio: 1,
        backgroundcolor: 'tomato',
        transform: [{ translateY:  headerHeight}],
      }}
    />
  );
};