API and Configuration

Available imports

• Router
• Scene
• Tabs
• Stack
• Tabbed Scene
• Drawer
• Modal
• Lightbox
• Actions
• NavigationStore
• ActionConst

Router:

Property	Type	Default	Description
backAndroidHandler	Function		Allows custom control of hardwareBackPress in Android (optional). For more info check BackHandler.
children		semi-required	Scene root element (required if navigator is not set)
navigator	Class		Application navigator with all Scenes created by Actions.create - it is altenative way to create Router, mostly used for Redux integration (see ReduxExample for more details)
onStateChange	Function		function to be called every time when navigation state is changed. Useful for mobx stores to change observables (set scene to Actions.currentScene, etc.)
sceneStyle	Style		Style applied to all scenes (optional)
uriPrefix	string		A uri prefix to strip from incoming urls for deep linking. For example, if you wanted to support deep linking from www.example.com/user/1234/, then you could pass example.com to only match paths against /user/1234/.
wrapBy	Function		function to wrap each Scene component and nav bar buttons - allows easy MobX integration (by passing observer)
navigationStore	NavigationStore	If you don't want to use singleton Actions, you can pass a custom new NavigationStore() as prop to Router

Scene:

The basic routing component for this router, all <Scene> components require a key prop that must be unique. A parent <Scene> must have a component as a prop as it will act as a grouping component for its children.

All properties of type React.Component will receive the same properties available on the Scene.

Property	Type	Default	Description
key	string	required	Will be used to call screen transition, for example, Actions.name(params). Must be unique.
path	string		Will be used to match against incoming deep links and pull params. For example, the path /user/:id/ would specify to call the Scene's action with params { id: 1234 } from the url /user/1234/. Should adhere to widely accepted uri templating standard https://tools.ietf.org/html/rfc6570
component	React.Component	semi-required	The Component to be displayed. Not required when defining a nested Scene, see example.
back	boolean	false	If it is true back button is displayed instead of left/drawer button defined by upper container.
backButtonImage	string		Image source to substitute for the nav back button
backButtonTextStyle	Style		Style applied to back button text
backButtonTintColor	string		Custom back button tint color
backTitle	string		Specifies the back button title for scene
backTitleEnabled	boolean		allows you to force back button titles to either be rendered or not (if you disagree with defaults for your platform and layout preset)
clone	boolean	false	Scenes marked with clone will be treated as templates and cloned into the current scene's parent when pushed. See example.
contentComponent	React.Component		Component used to render the content of the drawer (e.g. navigation items).
drawer	boolean	false	load child scenes inside DrawerNavigator
drawerLockMode	enum('unlocked', 'locked-closed', 'locked-open')		If a child of a drawer, specifies the lock mode of the drawer
failure	Function		If on returns a "falsey" value then failure is called.
headerMode	string	float	Specifies how the header should be rendered: float (render a single header that stays at the top and animates as screens are changed. This is a common pattern on iOS.), screen (each screen has a header attached to it and the header fades in and out together with the screen. This is a common pattern on Android) or none (No header will be rendered)
headerLayoutPreset	string	iOS: center Android: left	Change layout preset from header to be able to center text in some cases where it would be misaligned.
hideBackImage	boolean	false	hide back image
hideNavBar	boolean	false	hide the nav bar
init	boolean	false	If it is true back button will not be displayed
initial	boolean	false	Set to true if this is the first scene to display among its sibling Scenes
leftButtonIconStyle	Style		Style applied to left button Image
leftButtonImage	Image		Image to substitute for the left nav bar button
leftButtonStyle	Style		Style applied to left button
leftButtonTextStyle	Style		Style applied to left button text
modal	boolean	false	Defines scene container as 'modal' one, i.e. all children scenes will have bottom-to-top animation. It is applicable only for containers (different from v3 syntax)
navBar	React.Component		Optional React component to render custom NavBar
navBarButtonColor	string		Set the color of the back button in the navBar
navigationBarStyle	Style		Style applied to nav bar
navigationBarTitleImage	Object		The Image source that overrides the title in the navbar the image in the center of the navbar
navigationBarTitleImageStyle	object		Styles to apply to navigationBarTitleImage
navTransparent	boolean	false	nav bar background transparency
on	Function		aka onEnter
onBack	Function		Called when the back button is pressed.
onEnter	Function		Called when the Scene is navigated to. props are provided as a function param. Only scenes with 'component' defined is supported. Your component class may also have onEnter function
onExit	Function		Called when the Scene is navigated away from. Only scenes with 'component' defined is supported. Your component class may also have onExit function
onLeft	Function		Called when the left nav bar button is pressed.
onRight	Function		Called when the right nav bar button is pressed.
renderBackButton	React.Component		React component to render back button
renderLeftButton	React.Component		React component to render as the left button
renderRightButton	React.Component		React component to render as the right button
renderTitle	React.Component		React component to render title for nav bar
rightButtonImage	Image		Image to substitute for the right nav bar button
rightButtonStyle	Style		Style applied to right button image
rightButtonTextStyle	Style		Style applied to right button text
rightTitle	string		Specifies the right button title for scene
success	Function		If on returns a "truthy" value then success is called.
tabs	boolean	false	load child scenes as TabNavigator. Other Tab Navigator props also apply here.
title	string		Text to be displayed in the center of the nav bar.
titleStyle	Style		Style applied to the title
type	string	push	Optional type of navigation action. You could use replace to replace current scene with this scene
all other props			Any other props not listed here will be pass on to the specified Scene's component

Tabs (<Tabs> or <Scene tabs>)

Can use all props listed above in <Scene> as <Tabs> is syntatic sugar for <Scene tabs={true}>.

Property	Type	Default	Description
activeBackgroundColor	string		Specifies the active background color for the tab in focus
activeTintColor	string		Specifies the active tint color for tabbar icons
backToInitial	boolean	false	Back to initial screen on focused tab if tab icon was tapped. If your intention is to manage navigation from tabBarOnPress, do not set this prop true. Both props defined will make the tabBarOnPress passed to be wrapped and called in conjunction with the default handlers from tabbar.
hideTabBar	boolean	false	hide the tab bar
inactiveBackgroundColor	string		Specifies the inactive background color for the tabs not in focus
inactiveTintColor	string		Specifies the inactive tint color for tabbar icons
indicatorStyle	object		Override the style for active tab indicator.
labelStyle	object		Overrides the styles for the tab label
lazy	boolean	false	Won't render/mount the tab scene until the tab is active
showLabel	boolean	true	Boolean to show or not the tabbar icons labels
tabBarComponent	React.Component		React component to render custom tab bar
tabBarOnPress	function		Custom tab bar icon press.
tabBarPosition	string		Specifies tabbar position. Defaults to bottom on iOS and top on Android.
tabBarStyle	object		Override the tabbar styles
tabStyle	object		Override the style for an individual tab of the tabbar
upperCaseLabel	boolean	true	Whether to make label uppercase, default is true.
wrap	boolean	true	Wrap each scene with own navbar automatically (if it is not another container).

Custom Tab Bar Component

To implement a custom tab bar, import your component and assign it to the tabBarComponent prop in <Tabs>.

// ... import components
<Tabs
  key="tabBar"
  tabBarComponent={CustomTabBar}
>
  <Scene key="tab1" component={TabOne} title="Tab1"/>
  <Scene key="tab2" component={TabTwo} title="Tab2"/>
</Tabs>

Sample code for a custom tab bar component that will navigate to scene when tab is clicked:

import React from 'react';
import { Text, View, TouchableOpacity } from 'react-native';
import { Actions } from 'react-native-router-flux';

export default class CustomTabBar extends React.Component {
  render() {
    const { state } = this.props.navigation;
    const activeTabIndex = state.index;

    return (
      <View>
        {
          state.routes.map(element => (
            <TouchableOpacity key={element.key} onPress={() => Actions[element.key]()}>
              <Text>{element.key.toUpperCase()}</Text>
            </TouchableOpacity>
          ))
        }
      </View>
    );
  }
}

LegacyTabs (<LegacyTabs> or <Scene tabs={true} legacy={true}>)

Can use all props listed above in <Scene> as <LegacyTabs> is syntatic sugar for <Scene tabs={true} legacy={true}>.

Property	Type	Default	Description
activeBackgroundColor	string		Specifies the active background color for the tab in focus
activeTintColor	string		Specifies the active tint color for tabbar icons
animationEnabled	boolean	true	Enable or disable tab swipe animation.
backToInitial	boolean	false	Back to initial screen on focused tab if tab icon was tapped.
hideTabBar	boolean	false	hide the tab bar
inactiveBackgroundColor	string		Specifies the inactive background color for the tabs not in focus
inactiveTintColor	string		Specifies the inactive tint color for tabbar icons
indicatorStyle	object		Override the style for active tab indicator.
labelStyle	object		Overrides the styles for the tab label
lazy	boolean	false	Won't render/mount the tab scene until the tab is active
showLabel	boolean	true	Boolean to show or not the tabbar icons labels
swipeEnabled	boolean	false	Enable or disable swiping tabs.
tabBarComponent	React.Component		React component to render custom tab bar
tabBarOnPress	function		Custom tab bar icon press.
tabBarPosition	string		Specifies tabbar position. Defaults to bottom on iOS and top on Android.
tabBarStyle	object		Override the tabbar styles
tabStyle	object		Override the style for an individual tab of the tabbar
upperCaseLabel	boolean	true	Whether to make label uppercase, default is true.
wrap	boolean	true	Wrap each scene with own navbar automatically (if it is not another container).

Stack (<Stack>)

A component to group Scenes together for its own stack based navigation. Using this will create a separate navigator for this stack, so expect two navbars to appear unless you add hideNavBar.

Tab Scene (child <Scene> within Tabs)

A Scene that is a direct child of Tabs and can use all props listed above in Scene,

Property	Type	Default	Description
icon	component	undefined	a React Native component to place as a tab icon
tabBarLabel	string		The string to override a tab label

Drawer (<Drawer> or <Scene drawer>)

Can use all prop as listed in Scene as <Drawer>, syntatic sugar for <Scene drawer={true}>

Property	Type	Default	Description
drawerIcon	React.Component		Arbitrary component to be used for drawer 'hamburger' icon, you have to set it together with drawer prop
drawerImage	Image		Image to substitute drawer 'hamburger' icon, you have to set it together with drawer prop
drawerPosition	string	left	Determines whether the drawer is on the right or the left. Keywords accepted are right and left
drawerWidth	number		The width, in pixels, of the drawer (optional)
hideDrawerButton	boolean	false	Boolean to show or not the drawerImage or drawerIcon

Modals (<Modal> or <Scene modal>)

To implement a modal, you must use <Modal> as the root scene in your Router. The Modal will render the first scene (should be your true root scene) normally, and all following To display a modal use <Modal> as root renderer, so it will render the first element as normal scene and all others as popups (when they are pushed).

Example: In the example below, the root Scene is nested within a <Modal>, since it is the first nested Scene, it will render normally. If one were to push to statusModal, errorModal or loginModal, they will render as a Modal and by default will pull up from the bottom of the screen. It is important to note that currently the Modal does not allow for transparent backgrounds.

//... import components
<Router>
  <Modal>
    <Scene key="root">
      <Scene key="screen1" initial={true} component={Screen1} />
      <Scene key="screen2" component={Screen2} />
    </Scene>
    <Scene key="statusModal" component={StatusModal} />
    <Scene key="errorModal" component={ErrorModal} />
    <Scene key="loginModal" component={LoginModal} />
  </Modal>
</Router>

Lightbox (<Lightbox>)

Lightbox is a component used to render a component on top of the current Scene. Unlike modal, it will allow for resizing and transparency of the background.

Example: In the example below, the root Scene is nested within a <Lightbox>, since it is the first nested Scene, it will render normally. If one were to push to loginLightbox, they will render as a Lightbox and by default will lay on top of the current Scene allowing for transparent backrounds.

//... import components
<Router>
  <Lightbox>
    <Scene key="root">
      <Scene key="screen1" initial={true} component={Screen1} />
      <Scene key="screen2" component={Screen2} />
    </Scene>

    {/* Lightbox components will lay over the screen, allowing transparency*/}
    <Scene key="loginLightbox" component={loginLightbox} />
  </Lightbox>
</Router>

Actions

This Object is the main utility is to provide navigation features to your application. Assuming your Router and Scenes are configured properly, use the properties listed below to navigate between scenes. Some offer the added functionality to pass React props to the navigated scene.

These can be used directly, for example, Actions.pop() will dispatch correspond action written in the source code, or, you can set those constants in scene type, when you do Actions.main(), it will dispatch action according to your scene type or the default one.

Property	Type	Parameters	Description
[key]	Function	Object	The Actions object "automagically" uses the Scene's key prop in the Router to navigate. To navigate to a scene, call Actions.key() or Actions[key].call().
create	React.Element	(rootScene: Scene, props: Object, wrapBy: Function)	pass Scene to create your app navigator and the Props the Router should receive. It is alternative router creation method mostly used for Redux integration
currentScene	String		Returns the current scene that is active
drawerClose	Function		Closes the Drawer if applicable
drawerOpen	Function		Opens the Drawer if applicable
jump	Function	(sceneKey: String, props: Object)	used to switch to a new tab. For Tabs only.
pop	Function		Go back to the previous scene by "popping" the current scene off the nav stack
popTo	Function	(sceneKey: String, props: Object)	Pops the navigation stack until the Scene with the specified key is reached.
push	Function	(sceneKey: String, props: Object)	Pushes the scene to the stack, performing a transition to the new scene.
ref	Object		Allow access to component instance through it's ref on onEnter and onExit events in the Scene
refresh	Function	(props: Object)	Reloads the current scene by loading new props into the Scene
replace	Function	(sceneKey: String, props: Object)	Pops the current scene from the stack and pushes the new scene to the navigation stack. *No transition will occur.
reset	Function	(sceneKey: String, props: Object)	Clears the routing stack and pushes the scene into the first index. No transition will occur.

If you're having problem accessing Actions.ref.your_component_ref, try checking if it is undefined first before accessing it's values, so it can access the reference after the component is mounted. An example:

onEnter={() => {
if(Actions.refs.your_component_ref !== undefined) { 
  //now you can access it's properties without trouble
  Actios.refs.your_component_ref.selector.props.someCoolFunction();
  }
}}

NavigationStore

NavigationStore is the class that Actions is an instance of. In other words, Actions is the singleton instance of NavigationStore — but if you prefer, you can instantiate a NavigationStore on your own and pass it to Router explicitly.

ActionConst

Type constants to determine Scene transitions, These are PREFERRED over typing their values manually as these are subject to change as the project is updated.

Property	Type	Value	Shorthand
ActionConst.ANDROID_BACK	string	'REACT_NATIVE_ROUTER_FLUX_ANDROID_BACK'	N/A
ActionConst.BACK_ACTION	string	'REACT_NATIVE_ROUTER_FLUX_BACK_ACTION'	pop
ActionConst.BACK	string	'REACT_NATIVE_ROUTER_FLUX_BACK'	pop
ActionConst.BLUR	string	'REACT_NATIVE_ROUTER_FLUX_BLUR'	N/A
ActionConst.FOCUS	string	'REACT_NATIVE_ROUTER_FLUX_FOCUS'	N/A
ActionConst.JUMP	string	'REACT_NATIVE_ROUTER_FLUX_JUMP'	jump
ActionConst.POP_TO	string	'REACT_NATIVE_ROUTER_FLUX_POP_TO'	popTo
ActionConst.PUSH_OR_POP	string	'REACT_NATIVE_ROUTER_FLUX_PUSH_OR_POP'	push
ActionConst.PUSH	string	'REACT_NATIVE_ROUTER_FLUX_PUSH'	push
ActionConst.REFRESH	string	'REACT_NATIVE_ROUTER_FLUX_REFRESH'	refresh
ActionConst.REPLACE	string	'REACT_NATIVE_ROUTER_FLUX_REPLACE'	replace
ActionConst.RESET	string	'REACT_NATIVE_ROUTER_FLUX_RESET'	reset

Universal and Deep Linking

Use Case

• Consider a web app and mobile app pairing for a social network, which might have a url https://thesocialnetwork.com/profile/1234/.
• If we were building both a web app and a mobile app, we'd like to be able to express that uri scheme across platforms with the path /profile/:id/.
• On the web, we might want React-Router to to open up our <Profile /> component with the props { id: 1234 }.
• On mobile, if we've correctly set up our Android/iOS environment to launch our application and open our RNRF <Router />, then we also want to navigate to our mobile <Profile /> scene with the params { id: 1234 }

Usage

<Router uriPrefix={'thesocialnetwork.com'}>
  <Scene key="root">
     <Scene key={'home'} component={Home} />
     <Scene key={'profile'} path={"/profile/:id/"} component={Profile} />
     <Scene key={'profileForm'} path={"/edit/profile/:id/"} component={ProfileForm} />
  </Scene>
</Router>

If a user clicks on http://thesocialnetwork.com/profile/1234/ on their device, they'll open the <Router /> and then call Actions.profile({ id: 1234 })