Push Navigation

Defining States

After following the Setup instructions, you end up with an empty StateNavigator in App.js. The StateNavigator accepts an array of States that represent the scenes in your application. You give each scene a title that's displayed in the navigation bar on iOS. In an email application, for example, we might have States representing the inbox scene and the scenes for reading and writing a mail.

Both Android and iOS allow a user to navigate back through their stack of visited scenes. The Navigation router manages this stack by dropping a breadcrumb at each visited scene, like the fairy-tale characters Hansel and Gretel. You enable the breadcrumb trail by setting trackCrumbTrail to true against each State. In an email application, we set trackCrumbTrail to true on the 'mail' State so that the user can return to the 'inbox' scene after opening an email.

var stateNavigator = new StateNavigator([
  {key: 'inbox', title: 'Inbox'},
  {key: 'mail', title: 'Mail', trackCrumbTrail: true},
  {key: 'compose', title: 'Compose', trackCrumbTrail: true}
]);

Defining Scenes

Each State needs a matching scene which the Navigation router displays when that State is active. You define the scene in a function assigned to the renderScene property of the State. We can define two of the scenes in our email application using Inbox and Compose components.

var {inbox, compose} = stateNavigator.states;

inbox.renderScene = () => <Inbox />;
compose.renderScene = () => <Compose />;

Pushing

States become active by navigating to them. You navigate to a State by passing the State key to the navigate function of the StateNavigator. When our email application starts up, we navigate to the 'inbox' State so that the Navigation router displays the 'inbox' scene first.

stateNavigator.navigate('inbox');

You can access the StateNavigator inside any component using the React Context API. In our email example, we can add a button to the 'inbox' scene that navigates to the 'compose' State. Pressing the button pushes the 'compose' scene onto the stack. The user can return to their inbox using the Android back button or by pressing/swiping back on iOS.

import {NavigationContext} from 'navigation-react';

var Inbox = () => (
  <NavigationContext.Consumer>
    {({stateNavigator}) => (
      <TouchableHighlight
        onPress={() => {
          stateNavigator.navigate('compose');
        }}>
        <Text>Compose Mail</Text>
      </TouchableHighlight>
    )}
  </NavigationContext.Consumer>
);

Passing Data

You pass data between scenes via the second parameter of the navigate function. You can pass any data of type string, number, boolean and date; or any array of these types. When a user opens an email in our example app, we pass along the selected id to the 'mail' scene.

<TouchableHighlight
  onPress={() => {
    stateNavigator.navigate('mail', {id: 12});
  }}>
  <Text>Open Mail</Text>
</TouchableHighlight>

The Navigation router passes this navigation data into the renderScene function of the target State. In the email application, we can destructure the selected id from the incoming data and pass it as a prop to the Mail component.

var {mail} = stateNavigator.states;

mail.renderScene = ({id}) => <Mail mailId={id} />;

Note

Wrap each scene in a ScrollView component with contentInsetAdjustmentBehavior set to 'automatic' to prevent the iOS navigation bar overlapping the content