Skip to content

Latest commit

 

History

History
312 lines (274 loc) · 22.3 KB

API.md

File metadata and controls

312 lines (274 loc) · 22.3 KB

API and Configuration

Available imports

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