Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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

A routing library for React Native that strives for sensible API parity with react-router 🤖
https://github.com/jmurzy/react-router-native

react-native react-router

Last synced: 2 months ago
JSON representation

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

Awesome Lists containing this project

README 

        
# React Router Native [![CircleCI](https://img.shields.io/circleci/project/jmurzy/react-router-native/master.svg?style=flat-square)](https://circleci.com/gh/jmurzy/react-router-native) [![npm version](https://img.shields.io/npm/v/react-router-native.svg?style=flat-square)](https://www.npmjs.com/package/react-router-native) [![npm](https://img.shields.io/npm/l/react-router-native.svg?style=flat-square)](https://github.com/jmurzy/react-router-native/blob/master/LICENSE.md) [![Discord Channel](https://img.shields.io/badge/[email protected]?style=flat-square)](https://discord.gg/0ZcbPKXt5bYaNQ46) [![Medium](https://img.shields.io/badge/blog-medium-brightgreen.svg)](https://commitocracy.com/introducing-react-router-native-b02e76b8ca5d)



A routing library for [React Native](https://github.com/facebook/react-native) that strives for sensible API parity with [react-router](https://github.com/reactjs/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](https://github.com/reactjs/react-router/issues/743) similar to that of **NavigationExperimental** is better suited to native navigation. Transition to a reducer-based paradigm is also being [discussed](https://github.com/reactjs/react-router/issues/3190) for the web. On the other hand, NavigationExperimental [has no intention to support ](https://github.com/ericvicenti/navigation-rfc/issues/64#issuecomment-209001717) 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](https://github.com/facebook/react-native/commit/1dc33b5f23640a60682ac879b9a3e94a4aa519d9) 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](#platform-support)



**Note**: This project contains components that are currently under [active](https://github.com/facebook/react-native/commits?author=ericvicenti) [development](https://github.com/facebook/react-native/commits?author=hedgerwang) and considered experimental—aka use in production at your own risk.



### Installation



#### Using npm:



```sh

$ npm install --save react-router-native

```



#### Using yarn:



```sh

$ yarn add react-router-native

```



### Usage



```javascript

/**

 * 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) => (

  

    {props.children}

  

);



const HomeHeader = withRouter((props) => {

  const handleRightButtonPress = () => {

    props.router.push('/detail/gray');

  };



  return (

    

  );

});



const Home = () => {

  const DetailCard = ({ backgroundColor }) => (

    

      

    

  );



  return (

    

      

      

      

      

      

      

      

      

    

  );

};



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 (

    

  );

});



const Detail = (props) => (

  {props.children}

);



const routes = (

  /* Address Bar can be toggled on or off by setting the addressBar prop */

  

    

      

      

    

  

);



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

```



### Advanced Usage



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



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



```js

const reducer = (

  state: EnhancedNavigationState,

  action: NavigationAction

): EnhancedNavigationState => ({

  /* ... */

});



```



### Examples

The source includes a few [examples](/examples) that should help you get started. The example app from the GIF above can be found at `examples/Aviato`. You can also [view it with Exponent](https://exp.host/@rncommunity/aviato).



Route configuration for the example apps 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`](https://github.com/jmurzy/react-router-native/blob/b988ea696cca272296c424e7381df00944c9d062/examples/Aviato/app/routes.js#L23-L24) prop from the ```` component.



### Documentation

Documentation can be found [here](/docs).



### Platform Support



React Router Native is cross-platform. It supports all platforms that [NavigationExperimental](https://github.com/ericvicenti/navigation-rfc) supports.



### Contributing

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



### Questions?



Feel free to reach out to me on Twitter [@jmurzy](https://twitter.com/jmurzy). If you have any questions, please submit an Issue with the "[question](https://github.com/jmurzy/react-router-native/issues?utf8=%E2%9C%93&q=label%3Aquestion%20)" tag or come hang out in the React Router [Reactiflux Channel](https://discord.gg/0ZcbPKXt5bYaNQ46) and post your request there.



### Thanks



React Router Native is based on [React Router](https://github.com/reactjs/react-router). Thanks to Ryan Florence [@ryanflorence](https://twitter.com/ryanflorence), Michael Jackson [@mjackson](https://twitter.com/mjackson) and all the contributors for their work on [react-router](https://github.com/reactjs/react-router) and [history](https://github.com/mjackson/history).



Special thanks to Eric Vicenti [@ericvicenti](https://twitter.com/ericvicenti) and Hedger Wang [@hedgerwang](https://twitter.com/hedgerwang) for their work on [NavigationExperimental](https://github.com/ericvicenti/navigation-rfc).