react-router-native

React Router Native

A routing library for React Native that strives for sensible API parity with react-router.

Background

React Router community decided that a reducer-based paradigm similar to that of NavigationExperimental is better suited to native navigation. Transition to a reducer-based paradigm is also being discussed for the web. On the other hand, NavigationExperimental has no intention to support a React Router-like interface and leaves the navigation state up to the developer to maintain.

A declarative API removes the need to write boilerplate code and speeds up development. React Router Native follows React's Learn Once, Write Anywhere principle by providing a superset of React Router's API that marries React Router to NavigationExperimental.

Goals

• URL Driven Development
• Learn once, write anywhere: knowledge and proven idioms from react-router can be reused while extending them as necessary to allow navigation semantics unique to native platforms
• First class deep linking support
• Cross-platform

Note: This project contains components that are currently under active development and considered experimental—aka use in production at your own risk.

Installation

Using npm:

$ npm install --save react-router-native react-router

Do not let npm confuse you: there used to be another project with the same name that the previous owner nuked. Unfortunately, removing or re-publishing old versions is no longer supported by npm. So packages that are tagged < v2.0.0 on npm are artifacts of a different project, and the first stable version of this library will be released as v2.0.0 and strictly follow the React Versioning Scheme afterwards.

Usage

/**
 * index.[ios|android].js
 */

import React from 'react'
import { AppRegistry } from 'react-native';
import { Router, Route, TabsRoute, nativeHistory } from 'react-router-native';

const App = (props) => (/*...*/);
const About = (props) => (/*...*/);
const AboutHeader = (props) => (/*...*/);
const Users = (props) => (/*...*/);
const User = (props) => (/*...*/);
const UserHeader = (props) => (/*...*/);
const NoMatch = (props) => (/*...*/);

const routes = (
  /* Address Bar can be toggled on or off by setting the addressBar prop */
  <Router history={nativeHistory} addressBar>
    <TabsRoute
      path="app"
      component={App}
      transition="horizontal-pager"
    >
      <Route path="/" component={About} overlayComponent={AboutHeader}/>
      <Route path="users" component={Users} overlayComponent={UserHeader}>
        <Route path="/user/:userId" component={User}/>
      </Route>
    </TabsRoute>
    <Route path="*" component={NoMatch}/>
  </Router>
);

AppRegistry.registerComponent('YourApp', () => () => routes);

Advanced Usage

You can customize behavior of the default reducers that are used to create the navigationState of <Route> or its siblings.

This allows greater customizations on how <Link> behaves for a particular route and is especially useful for nested <StackRoute>'s where default action doesn't always lead to the intended behavior, or <TabsRoute>'s where double-taps should reset the navigationState of a nested <StackRoute>.

const reducer = (
  state: EnhancedNavigationState,
  action: NavigationAction
): EnhancedNavigationState => ({
  /* ... */
});

<TabsRoute path="/" component={Component} reducer={reducer}/>

Example

The example app from the GIF can be found at examples/Aviato. You can run it as follows:

git clone https://github.com/jmurzy/react-router-native

cd react-router-native/examples/Aviato
npm install
npm run ios

Look at app/routes.js and play around with the app to get a feel for what's possible. The address bar shown in the demo is used for development only and can be disabled by removing the addressBar prop from the <Router> component.

Documentation

Documentation can be found here.

Platform Support

React Router Native is cross-platform. It supports all platforms that NavigationExperimental supports.

Contributing

Want to hack on React Router Native? Awesome! We welcome contributions from anyone and everyone. Please see our guidelines for more information on workflow and setup.

Questions?

Feel free to reach out to me on Twitter @jmurzy. If you have any questions, please submit an Issue with the "question" tag or come hang out in the React Router Reactiflux Channel and post your request there.

Thanks

React Router Native is based on React Router. Thanks to Ryan Florence @ryanflorence, Michael Jackson @mjackson and all the contributors for their work on react-router and history.

Special thanks to Eric Vicenti @ericvicenti and Hedger Wang @hedgerwang for their work on NavigationExperimental.