A complete scene routing library written in pure JavaScript for React Native. It supports iOS and Android.
We, at Pressly, love react-router so much that we miss it in React Native world. So we decided to make one for react-native. I think if you already read this, I suggest don't stop reading and continue...
npm install scene-router
scene-router
has a declarative way of defining scenes hierarchy. Each Scene
tag defines a single path and component. Only the very first scene defines the initial path and initial props.
here's an example
<Scene initialPath="/home" initialProps={{}}>
<Scene path="home" component={Home}/>
<Scene path="about" component={About}/>
</Scene>
in the above example, we are defining 2 scenes. As soon as you run the app, Scene
will show you Home
component.
In order to transit between scene, scene-router
exposes two simple methods which can be called by accessing the Scene
object using ref
props.
Here's a simple example:
class MyAwesomeApp extends React.Component {
constructor(props, context) {
super(props, context);
}
componentDidMount() {
const scene = this.refs['sceneRef'];
setTimeout(() => {
scene.goto('/about');
}, 2000);
setTimeout(() => {
scene.goback();
}, 4000);
}
render() {
return (
<Scene ref="sceneRef" initialPath="/home" initialProps={{}} onSceneChange={({position, path}) => {
console.log(position, path);
}}>
<Scene path="home" component={Home}/>
<Scene path="about" component={About}/>
</Scene>
);
}
}
The above example transits to About
component after 2 seconds and transits back to Home
component after 2 seconds.
Don't worry about goto
and goback
we will talk about them in few mins.
This will be called once the scene is about to change. This is a good time to update any state in your main application such as redux
. The callback function gets one argument, event
, which contains position
and path
.
This method accepts 3 arguments. Only the first one is required. As you already figured this out, it transits to specific route, defined in the Scene
's
hierarchy.
So here's the method's definition:
goto(path, props, options);
- path: must be string
- props: an object map of key values which needs to be passed to component
- options: an object defines how scene transits. at the moment option can have only 2 keys.
withAnimation
andside
.- duration: is an integer value in millisecond, defining animation's duration. Default value is 2000.
- withAnimation: is a boolean value the default value is
true
. This flag enables animations between scenes. - side: is an enum which can be found in
scene-router
module asSceneSide
. it can be accessed byimport { SceneSide } from 'scene-router';
The default value isLEFT
. At the moment only 2 possible value is available.LEFT
andTOP
. - reset: is a boolean value. if it's true, it will clear scene stack. Reset stack will forces
withAnimation
tofalse
.
This method removes the last scene and transits back to the previous scene. It does not accept any arguments.
The power of scene-router
comes with its life cycle system. The scene-router
calls 4 new methods which can be implemented. These 4 methods are optional.
This method will be called once a scene has mounted and right before a transition starts. Do not do use heavy async calls here. It makes transition slow. Use it for small tasks.
This method will be called once the transition is completed. This is a good time for you to do network calls or heavy tasks.
This method will be called once another scene is planned to be focused. It is a good practice to clean or remove unnecessary elements from the scene to make the transition as smooth as possible.
This method will be called once the transition is done and the scene is not visible.
At the moment we are supporting query strings and params in our path.
For example:
<Scene initialPath="/user/1?showAll=true">
<Scene path="user/:id" component={User}/>
</Scene>
We define a route with variable params and navigate to that path with a new param, id, and query strings. All of these will be parsed and injected as params
and qs
props to User
component.
This enables you to do deeplinking
very easy and you can control where you want to go.
You can also nest Scene
s as well.
<Scene initialPath="/user/1?showAll=true">
<Scene path="user/:id" component={User}>
<Scene path="setting" component={UserSetting}/>
</Scene>
</Scene>
So now we can easily call scenePush('/user/1/settings')
and go to user's setting scene.
Please use it give us feedback and with help of you we can make it better.
Cheers.