/react-native-router-flux

React Native Router based on new React Native Navigation API

Primary LanguageJavaScriptMIT LicenseMIT

React Native Router Join the chat at https://gitter.im/aksonov/react-native-router-flux Codacy Badge npm version CircleCI

NPM
Router for React Native based on new React Native Navigation API.

Please check latest 4.0.0-beta.* , Example as demo: https://github.com/aksonov/react-native-router-flux/tree/v4

V4 Features:

  • Based on latest https://reactnavigation.org API
  • Separated navigation logic from presentation. You may change now navigation state directly from your business logic code - stores/reducers/etc. navigationStore
  • Built-in state machine (former Switch replacement) - each ‘scene’ has onEnter/onExit handlers. MobX-powered, all used scenes are wrapped as 'observer' automatically. You may subscribe to navigationStore (former Actions), observe current navigation state, etc. If you are using Redux, skip this.
  • Flexible nav bar customization, that is not allowed by react navigation right now: react-navigation/react-navigation#779
  • Drawer support (react
  • 'Lightbox' support (used by popups like Error alert within Example project)

Breaking changes (comparing to v3):

  1. No duration/panHandlers support - you have to implement custom navigator now instead and pass it as ‘navigator’ prop: https://reactnavigation.org/docs/navigators/custom

  2. No support for partial hiding of tab bar for some tabs because of react navigation bug: react-navigation/react-navigation#1584

  3. No possibility to skip animation during reset/replace: react-navigation/react-navigation#1493

  4. Switch is removed - you may use onEnter/onExit handlers for more flexible logic.

  5. getSceneStyle is removed (no needed in v4).

  6. Custom reducer (createReducer prop for Router) - Redux actions now are passed from React Navigation (‘Navigation/BACK’, ‘Navigation/NAVIGATE’, etc.)

  7. Drawer is 'drawer' attribute Scene

  8. Modal is 'modal' attribute for Scene

  9. No flux 'focus' actions - use onEnter/onExit handlers instead.

  10. Possible other stuff.

As you can see React Navigation still contains some issues, but anyway it is more stable than obsolete 'react-native-experimental-navigation' used by v3 now.

Here is link about road to v1 (so you can see all issues at one place): react-navigation/react-navigation#723

Documentation (v3)

Features

react-native-router-flux is a routing package that allows you to:

  • Define scene transitions in one central location
  • Without having to pass navigator objects around, and allow you to
  • Call transitions anywhere in your code with a simple syntax (e.g. Actions.login({username, password}) or Actions.profile({profile}) or even Actions.profile(123) - all params will be part of this.props for given Scene component).

New Features and Highlights

  • Highly Customizable Navigation Bar - Show/hide the navbar depending on Scene or even the state of a Scene (e.g. Edit/Save navbar for edit mode).

  • Tab Bar Support using react-native-tabs (see Example app).

  • Nested Navigators (e.g. Each tab can have its own navigator, nested in a root navigator).

  • Custom Scene Renderers for action sheet, native TabBarIOS or anything else. See built-in Modal renderer (to display popups) for example. Call for PRs! let's build some custom renderers for ActionSheet, Drawer, etc. Let's make an awesome library! Currently, if you want to use Action Sheets you'll need to use a 3rd party module.

  • Dynamic Routing allows you to choose which scene to render depending on application state (see the Switch renderer, useful for authentication).

  • Bring Your Own Reducer for navigation state.

  • Reset History Stack - The new resettype for clearing the history stack and eliminating the navbar back button.

  • More Powerful State Control - Support for having different states while on the same screen. For example, "View My Account" could allow in-place editing of fields and "Save", "Cancel" navigation bar buttons should appear.

Getting Started

Check out the mini-tutorial for a quick walkthrough of the routing system.

Supported configurations

While ExperimentalNavigation API is not stable, RNRF uses separated fork of ExperimentalNavigation API to avoid dependency from React Native version. So 3.30 version of RNRF doesn't depend from React Native version, but from that fork (now it is based on 0.26 API). You could use this component with RN0.26+

Installation

npm i react-native-router-flux --save

Usage

In your top-level index.js, define your scenes using the Scene component and pass it into the Router as children:

import {Scene, Router} from 'react-native-router-flux';

class App extends React.Component {
  render() {
    return <Router>
      <Scene key="root">
        <Scene key="login" component={Login} title="Login"/>
        <Scene key="register" component={Register} title="Register"/>
        <Scene key="home" component={Home}/>
      </Scene>
    </Router>
  }
}

Alternatively, you could define all of your scenes during compile time and use it later within Router:

import {Actions, Scene, Router} from 'react-native-router-flux';

const scenes = Actions.create(
  <Scene key="root">
    <Scene key="login" component={Login} title="Login"/>
    <Scene key="register" component={Register} title="Register"/>
    <Scene key="home" component={Home}/>
  </Scene>
);

/* ... */

class App extends React.Component {
  render() {
    return <Router scenes={scenes}/>
  }
}

On any Scene, you can also call the following functions by first importing the Actions object:

import {Actions} from 'react-native-router-flux'

And then:

  • Actions.ACTION_NAME(PARAMS) will call the appropriate action and params will be passed to the scene.
  • Actions.pop() will pop the current screen. It accepts following optional params:
    • {popNum: [number]} allows to pop multiple screens at once
    • {refresh: {...propsToSetOnPreviousScene}} allows to refresh the props of the scene that it pops back to
  • Actions.refresh(PARAMS) will update the properties of the current screen.

Production Apps using react-native-router-flux

  • Buddify (iOS, Android) - helps travelers discover fun things to do locally.
  • GuavaPass.com (iOS, Android) - offers convenient access to top classes at boutique fitness studios across Asia.
  • Epic Fail Videos (iOS, Android) - The best Fail Videos Collection, never miss a laugh with your friends!
  • Junk Free (iOS) - A simple way to find, share, and save recipes, workouts, and other healthy content with your friends, family and workmates.
  • chozun (iOS, Android) - Your travel companion, matching your lifestyle on the go!
  • Snappatizer (iOS) - Find and rank the best food around you.
  • Look Lock (GitHub, iOS, Android) - Show photos without worries.
  • BusDue, (iOS, Android) - London bus arrival time app

Support

Thanks to all who submitted PRs to 2.x release. If you like the component and want to support it, feel free to donate any amount or help with issues.