README.md

React Router Native

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

Please note that React Router v4 was just released. Over the next few weeks,
React Router Native will be refactored to make it fully compatible with v4.

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 [email protected] [email protected]

Usage

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

import React from 'react';
import {
  Header,
  Link,
  nativeHistory,
  Route,
  Router,
  StackRoute,
  withRouter,
} from 'react-router-native';
import {
  AppRegistry,
  ScrollView,
  StyleSheet,
  View,
} from 'react-native';

const styles = StyleSheet.create({
  component: {
    backgroundColor: '#FFFFFF',
    flex: 1,
  },
  home: {
    backgroundColor: '#FFFFFF',
    flexDirection: 'row',
    flexWrap: 'wrap',
    justifyContent: 'center',
  },
  detailCard: {
    height: 100,
    margin: 20,
    width: 100,
  },
});

const Master = (props) => (
  <View style={styles.component}>
    {props.children}
  </View>
);

const HomeHeader = withRouter((props) => {
  const handleRightButtonPress = () => {
    props.router.push('/detail/gray');
  };

  return (
    <Header
      {...props}
      style={{ backgroundColor: '#26BBE5' }}
      title="Feed"
      rightButtonText="Gray"
      onRightButtonPress={handleRightButtonPress}
    />
  );
});

const Home = () => {
  const DetailCard = ({ backgroundColor }) => (
    <Link to={`/detail/${encodeURIComponent(backgroundColor)}`} style={styles.detailCard}>
      <View style={{ flex: 1, backgroundColor }} />
    </Link>
  );

  return (
    <ScrollView style={styles.component} contentContainerStyle={styles.home}>
      <DetailCard backgroundColor="#EF4E5E" />
      <DetailCard backgroundColor="#9498CA" />
      <DetailCard backgroundColor="#AFCCB3" />
      <DetailCard backgroundColor="#F0D73D" />
      <DetailCard backgroundColor="#A176B0" />
      <DetailCard backgroundColor="#416BB4" />
      <DetailCard backgroundColor="#94B5DC" />
      <DetailCard backgroundColor="#D48445" />
    </ScrollView>
  );
};

const DetailHeader = withRouter((props) => {
  const { routeParams } = props;
  const title = routeParams.themeColor;
  const backgroundColor = routeParams.themeColor;
  const colors = ['#EF4E5E', '#D48445', '#AFCCB3', '#F0D73D', '#A176B0'];

  const handleRightButtonPress = () => {
    const randomIndex = Math.floor(Math.random() * colors.length);
    const randomColor = colors[randomIndex];
    props.router.push(`/detail/${encodeURIComponent(randomColor)}`);
  };

  return (
    <Header
      {...props}
      title={title}
      style={{ backgroundColor }}
      leftButtonText="Back"
      rightButtonText="Random"
      onRightButtonPress={handleRightButtonPress}
    />
  );
});

const Detail = (props) => (
  <View style={[styles.component, { backgroundColor: '#FFFFFF' }]}>{props.children}</View>
);

const routes = (
  /* Address Bar can be toggled on or off by setting the addressBar prop */
  <Router history={nativeHistory} addressBar>
    <StackRoute path="master" component={Master}>
      <Route path="/" component={Home} overlayComponent={HomeHeader} />
      <Route path="/detail/:themeColor" component={Detail} overlayComponent={DetailHeader} />
    </StackRoute>
  </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}/>

Examples

The source includes a few examples that should help you get started. The example app from the GIF above 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

To deploy to iOS simulator:

npm run ios

—or—

To deploy to Android simulator:

npm run android

Route configuration for the example app can be found in app/routes.js. 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.