React Native Easy Router

React Native Easy Router is an easy-to-use and performant screen navigation library for React Native

WARNING: Versions 2.x.x of this library is already not supported but you can find docs and examples here

If this project has helped you out, please support us with a star 🌟

Installation

npm install --save react-native-easy-router

Usage

import { AppRegistry, Text, View } from 'react-native'
import { name } from './app.json'
import React from 'react'
import Navigator from 'react-native-easy-router'

const First = ({ navigator }) => (
    <View
        style={{ alignItems: 'center', backgroundColor: 'white', flex: 1, flexDirection: 'column', justifyContent: 'center' }}>
        <Text>First screen</Text>
        <Text onPress={() => navigator.push('Second', { name: 'John' })}>Go forward</Text>
    </View>
)

const Second = ({ navigator, name }) => (
    <View
        style={{ alignItems: 'center', backgroundColor: 'pink', flex: 1, flexDirection: 'column', justifyContent: 'center' }}>
        <Text>Second screen</Text>
        <Text>Hello {name}!</Text>
        <Text onPress={() => navigator.pop()}>Go back</Text>
    </View>
)

const Application = () => <Navigator screens={{ First, Second }} initialStack='First' />

AppRegistry.registerComponent(name, () => Application)

You can look at example for better understanding

Documentation

Navigator properties

screens (required)

Screen components keyed by screen name

Example:

<Navigator screens={{ Welcome: ({navigator}) => <View><Text>Welcome</Text></View> }}/>

initialStack (required)

Initial stack can be a first screen name, an array of screen names or even array of screen objects that are are returned from navigator.stack or onStackUpdate.

Examples:

<Navigator initialStack='First'/>

or

<Navigator initialStack={['First', 'Second']}/>

or

<Navigator initialStack={[{screen: 'First', props: {name: 'John'}, transitionProps: {animation: 'left'}}]}/>

onStackUpdate

Callback that is called when stack updates

Example:

<Navigator onStackUpdate={(stack, previousStack) => console.log(stack, previousStack)}/>

backHandler

Default value: navigator => navigator.pop() Function that is called when user presses back button on Android or makes swipe back on IOS. If you return false from this function on Android app will be minimized.

Example:

<Navigator backHandler={navigator => navigator.pop()}/>

navigatorRef

Callback that is called on navigator initialization with navigator reference so you can manage your navigator from the outside.

Example:

<Navigator navigatorRef={ref => (this.navigator = ref)}/>

animations

Custom animations that you can use for transitions. Because navigator uses native transitions you can use only 'transform' animations. You can use this animation with any navigator method.

Example:

import { Dimensions } from 'react-native'
const { width: windowWidth, height: windowHeight } = Dimensions.get('window')

<Navigator animations={{
  bottomRight: {
      start: { transform: [{ translateX: windowWidth }, { translateY: windowHeight }] },
      end: { transform: [{ translateX: 0 }, { translateY: 0 }] }
  }
}}/>

Navigator methods

Navigator passes navigator object to every screen. With this object you can manage your screens. Also you can get this object with navigatorRef.

push(screen, props, transitionProps)

Pushes new screen to the stack. Returns Promise that is resolved after transition finishes.

Example:

  // Stack before: First
  navigator.push('Second', {email: '[email protected]'}, {animation: 'bottom'})
  // Stack after: First, Second

pop(transitionProps)

Pops last screen from the stack. If transitionProps are not provided uses those transitionProps that this screen was pushed with. Returns Promise that is resolved after transition finishes.

Example:

  // Stack before: First, Second
  navigator.pop({animation: 'left'})
  // Stack after: First

reset(screen, props, transitionProps)

Resets the whole stack to a new screen. Returns Promise that is resolved after transition finishes.

Example:

  // Stack before: First, Second
  navigator.reset('Third', {name: 'John'}, {animation: 'fade'})
  // Stack after: Third

stack

Returns the stack

Example:

  // Stack before: First, Second
  console.log(navigator.stack) // [{id: 'some-id', screen: 'First', props: {name: 'John'}, transitionProps: {animation: 'left', duration: 500, easing: 'ease-in-out'}}]

popTo(screenId, transitionProps)

Pops all screens after the certain screen. If transitionProps are not provided uses those transitionProps that this screen was pushed with. Returns Promise that is resolved after transition finishes.

Example:

  // Stack before: First, Second, Third, Fourth
  navigator.popTo(navigator.stack[1].id)
  // Stack after: First, Second

resetFrom(screenId, screen, props, transitionProps)

Resets the stack after the certain screen. Returns Promise that is resolved after transition finishes.

Example:

  // Stack before: First, Second, Third, Fourth
  navigator.resetFrom(navigator.stack[1].id, 'Fifth', {age: 18})
  // Stack after: First, Second, Fifth

register/unregisterBackHandler

If you want to handle Android hardware back press and IOS swipe back on the certain screen you can use this methods. If you return false from callback function on Android app will be minimized.

Example:

  componentDidMount = () => {
      this.props.navigator.registerBackHandler(this.onBack)
  }

  componentWillUnmount = () => {
      this.props.navigator.unregisterBackHandler()
  }

  onBack = navigator => navigator.pop()

Transition props

animation

Default value: 'right'

One of default animations: right, left, top, bottom, none, fade. Or one of custom animations provided to navigator by animations property.

duration

Default value: 250

Duration of transition in milliseconds. Not applied to none animation.

easing

Default value: 'ease-in-out'

One of easings from this table. Not applied to none animation.