Quick Start

Community Resources

Guides

Guides (iOS)

Guides (Android)

Polyfills

NavigatorIOS #

NavigatorIOS wraps UIKit navigation and allows you to add back-swipe functionality across your app.

NOTE: This Component is not maintained by Facebook
This component is under community responsibility. If a pure JavaScript solution fits your needs you may try the Navigator component instead.

Routes #

A route is an object used to describe each page in the navigator. The first route is provided to NavigatorIOS as initialRoute:

render: function() {
  return (
    <NavigatorIOS
      initialRoute={{
        component: MyView,
        title: 'My View Title',
        passProps: { myProp: 'foo' },
      }}
    />
  );
},

Now MyView will be rendered by the navigator. It will receive the route object in the route prop, a navigator, and all of the props specified in passProps.

See the initialRoute propType for a complete definition of a route.

Navigator #

A navigator is an object of navigation functions that a view can call. It is passed as a prop to any component rendered by NavigatorIOS.

var MyView = React.createClass({
  _handleBackButtonPress: function() {
    this.props.navigator.pop();
  },
  _handleNextButtonPress: function() {
    this.props.navigator.push(nextRoute);
  },
  ...
});

Navigator functions are also available on the NavigatorIOS component:

var MyView = React.createClass({
  _handleNavigationRequest: function() {
    this.refs.nav.push(otherRoute);
  },
  render: () => (
    <NavigatorIOS
      ref="nav"
      initialRoute={...}
    />
  ),
});

Props passed to the NavigatorIOS component will set the default configuration for the navigation bar. Props passed as properties to a route object will set the configuration for that route's navigation bar, overriding any props passed to the NavigatorIOS component.

Props #

barTintColor string #

The default background color of the navigation bar

initialRoute {component: function, title: string, passProps: object, backButtonIcon: Image.propTypes.source, backButtonTitle: string, leftButtonIcon: Image.propTypes.source, leftButtonTitle: string, onLeftButtonPress: function, rightButtonIcon: Image.propTypes.source, rightButtonTitle: string, onRightButtonPress: function, wrapperStyle: [object Object], navigationBarHidden: bool, shadowHidden: bool, tintColor: string, barTintColor: string, titleTextColor: string, translucent: bool} #

NavigatorIOS uses "route" objects to identify child views, their props, and navigation bar configuration. "push" and all the other navigation operations expect routes to be like this:

itemWrapperStyle View#style #

The default wrapper style for components in the navigator. A common use case is to set the backgroundColor for every page

navigationBarHidden bool #

A Boolean value that indicates whether the navigation bar is hidden by default

shadowHidden bool #

A Boolean value that indicates whether to hide the 1px hairline shadow by default

tintColor string #

The default color used for buttons in the navigation bar

titleTextColor string #

The default text color of the navigation bar title

translucent bool #

A Boolean value that indicates whether the navigation bar is translucent by default

Methods #

push(route: { component: Function; title: string; passProps?: Object; backButtonTitle?: string; backButtonIcon?: Object; leftButtonTitle?: string; leftButtonIcon?: Object; onLeftButtonPress?: Function; rightButtonTitle?: string; rightButtonIcon?: Object; onRightButtonPress?: Function; wrapperStyle?: any; }) #

Navigate forward to a new route

popN(n: number) #

Go back N pages at once. When N=1, behavior matches pop()

pop() #

Go back one page

replaceAtIndex(route: { component: Function; title: string; passProps?: Object; backButtonTitle?: string; backButtonIcon?: Object; leftButtonTitle?: string; leftButtonIcon?: Object; onLeftButtonPress?: Function; rightButtonTitle?: string; rightButtonIcon?: Object; onRightButtonPress?: Function; wrapperStyle?: any; }, index: number) #

Replace a route in the navigation stack.

index specifies the route in the stack that should be replaced. If it's negative, it counts from the back.

replace(route: { component: Function; title: string; passProps?: Object; backButtonTitle?: string; backButtonIcon?: Object; leftButtonTitle?: string; leftButtonIcon?: Object; onLeftButtonPress?: Function; rightButtonTitle?: string; rightButtonIcon?: Object; onRightButtonPress?: Function; wrapperStyle?: any; }) #

Replace the route for the current page and immediately load the view for the new route.

replacePrevious(route: { component: Function; title: string; passProps?: Object; backButtonTitle?: string; backButtonIcon?: Object; leftButtonTitle?: string; leftButtonIcon?: Object; onLeftButtonPress?: Function; rightButtonTitle?: string; rightButtonIcon?: Object; onRightButtonPress?: Function; wrapperStyle?: any; }) #

Replace the route/view for the previous page.

popToTop() #

Go back to the top item

popToRoute(route: { component: Function; title: string; passProps?: Object; backButtonTitle?: string; backButtonIcon?: Object; leftButtonTitle?: string; leftButtonIcon?: Object; onLeftButtonPress?: Function; rightButtonTitle?: string; rightButtonIcon?: Object; onRightButtonPress?: Function; wrapperStyle?: any; }) #

Go back to the item for a particular route object

replacePreviousAndPop(route: { component: Function; title: string; passProps?: Object; backButtonTitle?: string; backButtonIcon?: Object; leftButtonTitle?: string; leftButtonIcon?: Object; onLeftButtonPress?: Function; rightButtonTitle?: string; rightButtonIcon?: Object; onRightButtonPress?: Function; wrapperStyle?: any; }) #

Replaces the previous route/view and transitions back to it.

resetTo(route: { component: Function; title: string; passProps?: Object; backButtonTitle?: string; backButtonIcon?: Object; leftButtonTitle?: string; leftButtonIcon?: Object; onLeftButtonPress?: Function; rightButtonTitle?: string; rightButtonIcon?: Object; onRightButtonPress?: Function; wrapperStyle?: any; }) #

Replaces the top item and popToTop

Examples #

Edit on GitHub

'use strict';

const React = require('react');
const ReactNative = require('react-native');
const ViewExample = require('./ViewExample');
const createExamplePage = require('./createExamplePage');
const {
  AlertIOS,
  NavigatorIOS,
  ScrollView,
  StyleSheet,
  Text,
  TouchableHighlight,
  View,
} = ReactNative;

const EmptyPage = React.createClass({
  render: function() {
    return (
      <View style={styles.emptyPage}>
        <Text style={styles.emptyPageText}>
          {this.props.text}
        </Text>
      </View>
    );
  },
});

const NavigatorIOSExamplePage = React.createClass({
  render: function() {
    var recurseTitle = 'Recurse Navigation';
    if (!this.props.depth || this.props.depth === 1) {
      recurseTitle += ' - more examples here';
    }
    return (
      <ScrollView style={styles.list}>
        <View style={styles.line}/>
        <View style={styles.group}>
          {this._renderRow(recurseTitle, () => {
            this.props.navigator.push({
              title: NavigatorIOSExample.title,
              component: NavigatorIOSExamplePage,
              backButtonTitle: 'Custom Back',
              passProps: {depth: this.props.depth ? this.props.depth + 1 : 1},
            });
          })}
          {this._renderRow('Push View Example', () => {
            this.props.navigator.push({
              title: 'Very Long Custom View Example Title',
              component: createExamplePage(null, ViewExample),
            });
          })}
          {this._renderRow('Custom Right Button', () => {
            this.props.navigator.push({
              title: NavigatorIOSExample.title,
              component: EmptyPage,
              rightButtonTitle: 'Cancel',
              onRightButtonPress: () => this.props.navigator.pop(),
              passProps: {
                text: 'This page has a right button in the nav bar',
              }
            });
          })}
          {this._renderRow('Custom Left & Right Icons', () => {
            this.props.navigator.push({
              title: NavigatorIOSExample.title,
              component: EmptyPage,
              leftButtonTitle: 'Custom Left',
              onLeftButtonPress: () => this.props.navigator.pop(),
              rightButtonIcon: require('image!NavBarButtonPlus'),
              onRightButtonPress: () => {
                AlertIOS.alert(
                  'Bar Button Action',
                  'Recognized a tap on the bar button icon',
                  [
                    {
                      text: 'OK',
                      onPress: () => console.log('Tapped OK'),
                    },
                  ]
                );
              },
              passProps: {
                text: 'This page has an icon for the right button in the nav bar',
              }
            });
          })}
          {this._renderRow('Pop', () => {
            this.props.navigator.pop();
          })}
          {this._renderRow('Pop to top', () => {
            this.props.navigator.popToTop();
          })}
          {this._renderReplace()}
          {this._renderReplacePrevious()}
          {this._renderReplacePreviousAndPop()}
          {this._renderRow('Exit NavigatorIOS Example', this.props.onExampleExit)}
        </View>
        <View style={styles.line}/>
      </ScrollView>
    );
  },

  _renderReplace: function() {
    if (!this.props.depth) {
      // this is to avoid replacing the top of the stack
      return null;
    }
    return this._renderRow('Replace here', () => {
      var prevRoute = this.props.route;
      this.props.navigator.replace({
        title: 'New Navigation',
        component: EmptyPage,
        rightButtonTitle: 'Undo',
        onRightButtonPress: () => this.props.navigator.replace(prevRoute),
        passProps: {
          text: 'The component is replaced, but there is currently no ' +
            'way to change the right button or title of the current route',
        }
      });
    });
  },

  _renderReplacePrevious: function() {
    if (!this.props.depth || this.props.depth < 2) {
      // this is to avoid replacing the top of the stack
      return null;
    }
    return this._renderRow('Replace previous', () => {
      this.props.navigator.replacePrevious({
        title: 'Replaced',
        component: EmptyPage,
        passProps: {
          text: 'This is a replaced "previous" page',
        },
        wrapperStyle: styles.customWrapperStyle,
      });
    });
  },

  _renderReplacePreviousAndPop: function() {
    if (!this.props.depth || this.props.depth < 2) {
      // this is to avoid replacing the top of the stack
      return null;
    }
    return this._renderRow('Replace previous and pop', () => {
      this.props.navigator.replacePreviousAndPop({
        title: 'Replaced and Popped',
        component: EmptyPage,
        passProps: {
          text: 'This is a replaced "previous" page',
        },
        wrapperStyle: styles.customWrapperStyle,
      });
    });
  },

  _renderRow: function(title: string, onPress: Function) {
    return (
      <View>
        <TouchableHighlight onPress={onPress}>
          <View style={styles.row}>
            <Text style={styles.rowText}>
              {title}
            </Text>
          </View>
        </TouchableHighlight>
        <View style={styles.separator} />
      </View>
    );
  },
});

const NavigatorIOSExample = React.createClass({
  statics: {
    title: '<NavigatorIOS>',
    description: 'iOS navigation capabilities',
    external: true,
  },

  render: function() {
    const {onExampleExit} = this.props;
    return (
      <NavigatorIOS
        style={styles.container}
        initialRoute={{
          title: NavigatorIOSExample.title,
          component: NavigatorIOSExamplePage,
          passProps: {onExampleExit},
        }}
        itemWrapperStyle={styles.itemWrapper}
        tintColor="#008888"
      />
    );
  },
});

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  customWrapperStyle: {
    backgroundColor: '#bbdddd',
  },
  emptyPage: {
    flex: 1,
    paddingTop: 64,
  },
  emptyPageText: {
    margin: 10,
  },
  list: {
    backgroundColor: '#eeeeee',
    marginTop: 10,
  },
  group: {
    backgroundColor: 'white',
  },
  groupSpace: {
    height: 15,
  },
  line: {
    backgroundColor: '#bbbbbb',
    height: StyleSheet.hairlineWidth,
  },
  row: {
    backgroundColor: 'white',
    justifyContent: 'center',
    paddingHorizontal: 15,
    paddingVertical: 15,
  },
  separator: {
    height: StyleSheet.hairlineWidth,
    backgroundColor: '#bbbbbb',
    marginLeft: 15,
  },
  rowNote: {
    fontSize: 17,
  },
  rowText: {
    fontSize: 17,
    fontWeight: '500',
  },
});

module.exports = NavigatorIOSExample;

Run this example