API and Configuration

Available imports

Router
Scene
Tabs
Stack
Tabbed Scene
Drawer
Modal
Lightbox
Actions
ActionConst

Router:

Property	Type	Default	Description
children		required	Scene root element
`wrapBy`	`Function`		function to wrap each Scene component and nav bar buttons - allows easy MobX integration (by passing `observer`)
`sceneStyle`	`Style`		Style applied to all scenes (optional)
`backAndroidHandler`	`Function`		Allows custom control of hardwareBackPress in Android (optional). For more info check BackHandler.
`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/`.

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.

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
`backButtonTintColor`	`string`		Custom back button tint color
`init`	`boolean`	`false`	If it is `true` back button will not be displayed
`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
`failure`	`Function`		If `on` returns a "falsey" value then `failure` is called.
`backTitle`	`string`		Specifies the back button title for scene
`backButtonTextStyle`	`Style`		Style applied to back button text
`rightTitle`	`string`		Specifies the right button title for scene
`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)
`hideNavBar`	`boolean`	`false`	hide the nav bar
`hideTabBar`	`boolean`	`false`	hide the tab bar (only applies to scenes with `tabs` specified)
`hideBackImage`	`boolean`	`false`	hide back image
`initial`	`boolean`	`false`	Set to `true` if this is the first scene to display among its sibling `Scene`s
`leftButtonImage`	`Image`		Image to substitute for the left nav bar button
`leftButtonTextStyle`	`Style`		Style applied to left button text
`leftButtonStyle`	`Style`		Style applied to left button
`leftButtonIconStyle`	`Style`		Style applied to left button Image
`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.
`renderTitle`	`React.Component`		React component to render title for nav bar
`renderLeftButton`	`React.Component`		React component to render as the left button
`renderRightButton`	`React.Component`		React component to render as the right button
`renderBackButton`	`React.Component`		React component to render back button
`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
`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
`drawerLockMode`	enum('unlocked', 'locked-closed', 'locked-open')		If a child of a drawer, specifies the lock mode of the drawer (https://facebook.github.io/react-native/docs/drawerlayoutandroid.html#drawerlockmode)
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
`wrap`	`boolean`	`true`	Wrap each scene with own navbar automatically (if it is not another container).
`activeBackgroundColor`	`string`		Specifies the active background color for the tab in focus
`activeTintColor`	`string`		Specifies the active tint color for tabbar icons
`inactiveBackgroundColor`	`string`		Specifies the inactive background color for the tabs not in focus
`inactiveTintColor`	`string`		Specifies the inactive tint color for tabbar icons
`labelStyle`	`object`		Overrides the styles for the tab label
`lazy`	`boolean`	`false`	Won't render/mount the tab scene until the tab is active
`tabBarComponent`	`React.Component`		React component to render custom tab bar
`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
`showLabel`	`boolean`	`true`	Boolean to show or not the tabbar icons labels
`swipeEnabled`	`boolean`	`false`	Enable or disable swiping tabs.
`animationEnabled`	`boolean`	`true`	Enable or disable tab swipe animation.
`tabBarOnPress`	`function`		Custom tab bar icon press.
`backToInitial`	`boolean`	`false`	Back to initial screen on focused tab if tab icon was tapped.

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
`drawerImage`	`Image`		Image to substitute drawer 'hamburger' icon, you have to set it together with `drawer` prop
`drawerIcon`	`React.Component`		Arbitrary component to be used for drawer 'hamburger' icon, you have to set it together with `drawer` prop
`hideDrawerButton`	`boolean`	`false`	Boolean to show or not the drawerImage or drawerIcon
`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)

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()`.
`currentScene`	`String`		Returns the current scene that is active
`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.
`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.
`drawerOpen`	`Function`		Opens the `Drawer` if applicable
`drawerClose`	`Function`		Closes the `Drawer` if applicable

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.JUMP`	`string`	'REACT_NATIVE_ROUTER_FLUX_JUMP'	`jump`
`ActionConst.PUSH`	`string`	'REACT_NATIVE_ROUTER_FLUX_PUSH'	`push`
`ActionConst.PUSH_OR_POP`	`string`	'REACT_NATIVE_ROUTER_FLUX_PUSH_OR_POP'	`push`
`ActionConst.REPLACE`	`string`	'REACT_NATIVE_ROUTER_FLUX_REPLACE'	`replace`
`ActionConst.BACK`	`string`	'REACT_NATIVE_ROUTER_FLUX_BACK'	`pop`
`ActionConst.BACK_ACTION`	`string`	'REACT_NATIVE_ROUTER_FLUX_BACK_ACTION'	`pop`
`ActionConst.POP_TO`	`string`	'REACT_NATIVE_ROUTER_FLUX_POP_TO'	`popTo`
`ActionConst.REFRESH`	`string`	'REACT_NATIVE_ROUTER_FLUX_REFRESH'	`refresh`
`ActionConst.RESET`	`string`	'REACT_NATIVE_ROUTER_FLUX_RESET'	`reset`
`ActionConst.FOCUS`	`string`	'REACT_NATIVE_ROUTER_FLUX_FOCUS'	N/A
`ActionConst.BLUR`	`string`	'REACT_NATIVE_ROUTER_FLUX_BLUR'	N/A
`ActionConst.ANDROID_BACK`	`string`	'REACT_NATIVE_ROUTER_FLUX_ANDROID_BACK'	N/A

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 })

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API.md

API.md

API and Configuration

Available imports

Router:

Scene:

Tabs (`<Tabs>` or `<Scene tabs>`)

Stack (`<Stack>`)

Tab Scene (child `<Scene>` within `Tabs`)

Drawer (`<Drawer>` or `<Scene drawer>`)

Modals (`<Modal>` or `<Scene modal>`)

Lightbox (`<Lightbox>`)

Actions

ActionConst

Universal and Deep Linking

Use Case

Usage

Files

API.md

Latest commit

History

API.md

File metadata and controls

API and Configuration

Available imports

Router:

Scene:

Tabs (<Tabs> or <Scene tabs>)

Stack (<Stack>)

Tab Scene (child <Scene> within Tabs)

Drawer (<Drawer> or <Scene drawer>)

Modals (<Modal> or <Scene modal>)

Lightbox (<Lightbox>)

Actions

ActionConst

Universal and Deep Linking

Use Case

Usage

Tabs (`<Tabs>` or `<Scene tabs>`)

Stack (`<Stack>`)

Tab Scene (child `<Scene>` within `Tabs`)

Drawer (`<Drawer>` or `<Scene drawer>`)

Modals (`<Modal>` or `<Scene modal>`)

Lightbox (`<Lightbox>`)