API.md

API and Configuration

Available imports

• Router
• Scene
• Tabs
• 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> cannot not 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 Scenes
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
onExit	Function		Called when the Scene is navigated away from. Only scenes with 'component' defined is supported
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
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
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 })