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 |
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 Scene s |
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 |
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). |
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>
);
}
}
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). |
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
.
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 |
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 |
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 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>
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
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.
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 |
- 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 theprops
{ 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 theparams
{ id: 1234 }
<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 })