A step-by-step guide to building your own navigator in JavaScript for React Native
Build a JavaScript Navigator for React Native
Navigation is a hot, and often contested, topic in React Native. It's something nearly every app has, multiple solutions exists, and they each have their pros and cons.
There are great solutions out there (React Navigation and React Native Navigation are my top choices) but I think building a navigator is a great exercise to further your understanding of React Native. It forces you to design an API, work with animations, handle gestures, and more.
So that's what we'll do today. We'll build a basic JavaScript navigator for React Native.
Requirements
We're going to build a navigator that allows us to keep a stack of cards. It should
- have a simple declarative API
- allow us to push new screens onto the stack
- pop the current screen off the stack and go to the previous screen
- animate between screen transitions
- handle user gestures for swiping back (covered in part 2)
Getting Started
I'll be using create-react-native-app to create my project. You can run the following in your terminal
create-react-native-app rn-js-navigator
You can then run the app on an iOS or Android simulator with yarn run ios or yarn run android, respectively.
API Design
The navigator will have one Navigator component with which we wrap all of the valid screens. Each screen we want to register with the navigator will be passed in a Route component. Like this:
<Navigator>
<Route name="Screen1" component={Screen1} />
<Route name="Screen2" component={Screen2} />
<Route name="Screen3" component={Screen3} />
</Navigator>
The top level Navigator component is where all the actual work happens. The Route component allows us to pass various properties/configuration down for each screen - in this case a name (which will be used to specify which screen should be pushed) and a component (which component should actually be rendered).
Each route will get a navigator prop passed to it and on that navigator prop a push and pop function will be on it. Allowing for the following type of interaction:
const Screen2 = ({ navigator }) => (
<View style={[styles.screen, { backgroundColor: '#23395B' }]}>
<Button
title="Screen 3"
onPress={() => navigator.push('Screen3')}
/>
<Button
title="Pop"
onPress={() => navigator.pop()}
/>
</View>
);
Alright, with the basic API outlined, lets get to writing some code.
Boilerplate
First, let's create the three screens we'll use in our app. In App.js replace the file with the following
App.js
import React from 'react';
import { StyleSheet, View, Button } from 'react-native';
const Screen1 = ({ navigator }) => (
<View style={[styles.screen, { backgroundColor: '#59C9A5' }]}>
<Button
title="Screen 2"
onPress={() => navigator.push('Screen2')}
/>
<Button
title="Pop"
onPress={() => navigator.pop()}
/>
</View>
);
const Screen2 = ({ navigator }) => (
<View style={[styles.screen, { backgroundColor: '#23395B' }]}>
<Button
title="Screen 3"
onPress={() => navigator.push('Screen3')}
/>
<Button
title="Pop"
onPress={() => navigator.pop()}
/>
</View>
);
const Screen3 = ({ navigator }) => (
<View style={[styles.screen, { backgroundColor: '#B9E3C6' }]}>
<Button
title="Pop"
onPress={() => navigator.pop()}
/>
</View>
);
export default Screen1;
const styles = StyleSheet.create({
screen: {
flex: 1,
alignItems: 'center',
justifyContent: 'center',
},
});
Now, let's create a Navigator.js file in which all of our navigation logic will live. Right now it's just going to be a skeleton of the exported components.
Navigator.js
import React from 'react';
export const Route = () => null;
export class Navigator extends React.Component {
render() {
return null;
}
}
Now, lets go back to App.js and use these new components to define our routes.
First we need to import our components.
App.js
import { Navigator, Route } from './Navigator';
The replace
export default Screen1;
with
App.js
export default class App extends React.Component {
render() {
return (
<Navigator>
<Route name="Screen1" component={Screen1} />
<Route name="Screen2" component={Screen2} />
<Route name="Screen3" component={Screen3} />
</Navigator>
);
}
}
If you see a blank white screen you're exactly where you should be!
Rendering Screens
All of our screens are accessible via this.props.children in the Navigator component. You could render the first screen via
Navigator.js
export class Navigator extends React.Component {
render() {
const CurrentScene = this.props.children[0].props.component;
return <CurrentScene />;
}
}
which should now show the green Screen1 again. This works, but accessing everything via this.props.children won't work very well going forward. We're going to need some internal state.
First, we'll store a stack array which will track the current stack of rendered screens. It should default to the first child of Navigator. We're also going to create an easier to use sceneConfig object that will allow us to access all of the data we need quickly when pushing a new screen onto the stack.
First we'll create a buildSceneConfig function that accepts the Navigator children as an argument.
Navigator.js
const buildSceneConfig = (children = []) => {
const config = {};
children.forEach(child => {
config[child.props.name] = { key: child.props.name, component: child.props.component };
});
return config;
};
Inside of this function we'll populate an object that represents our sceneConfig. This results in the following data.
{
Scene1: {
key: 'Scene1',
component: Scene1,
},
Scene2: {
key: 'Scene2',
component: Scene2,
},
Scene2: {
key: 'Scene2',
component: Scene2,
},
}
We can then use this function in the constructor of the Navigator component and store the result in state. We can also populate our stack with the first screen.
Navigator.js
export class Navigator extends React.Component {
constructor(props) {
super(props);
const sceneConfig = buildSceneConfig(props.children);
const initialSceneName = props.children[0].props.name;
this.state = {
sceneConfig,
stack: [sceneConfig[initialSceneName]],
};
}
// ...
}
We can then use this.state.stack to render our screen.
Navigator.js
export class Navigator extends React.Component {
constructor(props) {
super(props);
const sceneConfig = buildSceneConfig(props.children);
const initialSceneName = props.children[0].props.name;
this.state = {
sceneConfig,
stack: [sceneConfig[initialSceneName]],
};
}
render() {
const CurrentScene = this.state.stack[0].component;
return <CurrentScene />;
}
}
Push Action
If you were to press "Screen 2" at this point the app will error with Cannot read property 'push' of undefined.
That's because we aren't yet passing a navigator prop down to the scene. In this navigator prop we'll pass the push action. Let's write that push handler now.
Navigator.js
export class Navigator extends React.Component {
constructor(props) { ... }
handlePush = (sceneName) => {
this.setState(state => ({
...state,
stack: [...state.stack, state.sceneConfig[sceneName]],
}));
}
render() { ... }
}
All we're doing here is accepting a sceneName, which should correspond to a name prop given to one of our Route components and then finding the corresponding scene config for that route and adding it to the stack.
We then need to make the push function available to the current scene.
Navigator.js
export class Navigator extends React.Component {
constructor(props) { ... }
handlePush = (sceneName) => {
this.setState(state => ({
...state,
stack: [...state.stack, state.sceneConfig[sceneName]],
}));
}
render() {
const CurrentScene = this.state.stack[0].component;
return <CurrentScene navigator={{ push: this.handlePush }} />;
}
}
If you press "Screen 2" now no error occurs! But also nothing changes, despite the state change. Let's fix that.
To do so we'll need to loop over this.state.stack and render the screens (we'll take care of styling later).
First you'll need to import some components from React Native.
Navigator.js
import { View, StyleSheet } from 'react-native';
We'll then loop over this.state.stack and render each scene. We'll also set up some styling for the container view.
Navigator.js
export class Navigator extends React.Component {
// ...
render() {
return (
<View style={styles.container}>
{this.state.stack.map((scene, index) => {
const CurrentScene = scene.component;
return (
<CurrentScene
key={scene.key}
navigator={{ push: this.handlePush }}
/>
);
})}
</View>
)
}
}
const styles = StyleSheet.create({
container: {
flex: 1,
flexDirection: 'row',
},
});
When you press a screen name you should now see something like this.
Pop Action
Before we fix the styling, let's add a pop action.
Navigator.js
export class Navigator extends React.Component {
// ...
handlePop = () => {
this.setState(state => {
const { stack } = state;
if (stack.length > 1) {
return {
stack: stack.slice(0, stack.length - 1),
};
}
return state;
});
}
render() {
return (
<View style={styles.container}>
{this.state.stack.map((scene, index) => {
const CurrentScene = scene.component;
return (
<CurrentScene,
key={scene.key}
navigator={{ push: this.handlePush, pop: this.handlePop }}
/>
);
})}
</View>
)
}
}
In the handlePop function we're checking if the stack has more than one screen and, if so, we remove the last screen in that stack.
Make sure you pass the pop function down on the navigator prop!
Styling
To ensure screens show up on top of each other we'll use absolute positioning. StyleSheet.absoluteFillObject is a nice short hand option for this.
Navigator.js
export class Navigator extends React.Component {
// ...
render() {
return (
<View style={styles.container}>
{this.state.stack.map((scene, index) => {
const CurrentScene = scene.component;
return (
<View key={scene.key} style={styles.scene}>
<CurrentScene
navigator={{ push: this.handlePush, pop: this.handlePop }}
/>
</View>
);
})}
</View>
)
}
}
const styles = StyleSheet.create({
// ...
scene: {
...StyleSheet.absoluteFillObject,
flex: 1,
},
});
Notice that we're wrapping CurrentScreen component in a View component to apply the styles. We also need a flex: 1 so the view takes up the entire screen. Notice also that the key moved from CurrentScene to the View.
Animation
Alright, final thing for this tutorial. The animation! We're going to do a right-to-left animation, as is typical on iOS.
First let's take care of a few modules we need to import.
Navigator.js
import { View, StyleSheet, Animated, Dimensions } from 'react-native';
const { width } = Dimensions.get('window');
We need Animated to manage animations efficiently and Dimensions so we can get the width of the screen.
We'll then intialize a new _animatedValue on the component to drive the slide animation.
Navigator.js
export class Navigator extends React.Component {
// ...
_animatedValue = new Animated.Value(0);
// ...
}
Now that the boilerplate is setup, let's add the right-to-left animation when you push a new screen onto the stack.
It's important to do this at the right time. The right time in this case is after we've updated the state. That means we'll start the animation in the setState callback.
Navigator.js
export class Navigator extends React.Component {
// ...
handlePush = (sceneName) => {
this.setState(state => ({
...state,
stack: [...state.stack, state.sceneConfig[sceneName]],
}), () => {
this._animatedValue.setValue(width);
Animated.timing(this._animatedValue, {
toValue: 0,
duration: 250,
useNativeDriver: true,
}).start();
});
}
// ...
}
First we set the _animatedValue to the width of the screen. That's what the starting offset will be. If you wanted it offset to the left then it would be -width.
Once we set that value we actually do the animation. This animation brings the offset to 0 or fully visible on the screen. The duration I set is an arbitrary value.
Finally, notice that I'm using useNativeDriver. This is an important thing to do when working with Animations in React Native as it will provide better performance of your animations and reduce the likelihood of "jitter" in your animations.
Now that we're setting the values correctly we need to apply them, which will happen in the render function.
Navigator.js
export class Navigator extends React.Component {
// ...
render() {
return (
<View style={styles.container}>
{this.state.stack.map((scene, index) => {
const CurrentScene = scene.component;
// Create an array of styles for the scene
const sceneStyles = [styles.scene];
// If we're on the last screen and there's more than one screen in the stack then animation makes sense.
if (index === this.state.stack.length - 1 && index > 0) {
sceneStyles.push({
transform: [
{
translateX: this._animatedValue,
}
]
});
}
// Convert the View to Animated.View
return (
<Animated.View key={scene.key} style={sceneStyles}>
<CurrentScene
navigator={{ push: this.handlePush, pop: this.handlePop }}
/>
</Animated.View>
);
})}
</View>
)
}
}
Okay, there's a bit going on here. First off we're setting up a sceneStyles array for the containing scene view as the styles can be different between screens.
We then determine whether a screen should be animated. An animation only makes sense when there is more than 1 screen in the stack. We also only want to apply the styles to the active/last screen.
We then use a transform style, where we target the translateX value, to apply the this._animatedValue value. When you use useNativeDriver you're limited on which values you can modify - transform props are one of them!
Finally, we moved from View to Animated.View and passed the sceneStyles to the style prop.
That leaves us with the following.
Woo! Progress. Now the pop action.
This time we want to run our animation before we update state because we only want to remove the screen from state after it's off screen. Make sense?
Navigator.js
export class Navigator extends React.Component {
// ...
handlePop = () => {
Animated.timing(this._animatedValue, {
toValue: width,
duration: 250,
useNativeDriver: true,
}).start(() => {
this._animatedValue.setValue(0);
this.setState(state => {
const { stack } = state;
if (stack.length > 1) {
return {
stack: stack.slice(0, stack.length - 1),
};
}
return state;
});
});
}
// ...
}
First we'll make our offset go to the screen width. Once the animation is complete (which we know by the callback in the .start function being called) we need to make sure to reset our offset to 0 so that the new active screen is fully visible.
Final Code
The final code for Navigator.js:
Navigator.js
import React from 'react';
import { View, StyleSheet, Animated, Dimensions } from 'react-native';
const { width } = Dimensions.get('window');
export const Route = () => null;
const buildSceneConfig = (children = []) => {
const config = {};
children.forEach(child => {
config[child.props.name] = { key: child.props.name, component: child.props.component };
});
return config;
};
export class Navigator extends React.Component {
constructor(props) {
super(props);
const sceneConfig = buildSceneConfig(props.children);
const initialSceneName = props.children[0].props.name;
this.state = {
sceneConfig,
stack: [sceneConfig[initialSceneName]],
};
}
_animatedValue = new Animated.Value(0);
handlePush = (sceneName) => {
this.setState(state => ({
...state,
stack: [...state.stack, state.sceneConfig[sceneName]],
}), () => {
this._animatedValue.setValue(width);
Animated.timing(this._animatedValue, {
toValue: 0,
duration: 250,
useNativeDriver: true,
}).start();
});
}
handlePop = () => {
Animated.timing(this._animatedValue, {
toValue: width,
duration: 250,
useNativeDriver: true,
}).start(() => {
this._animatedValue.setValue(0);
this.setState(state => {
const { stack } = state;
if (stack.length > 1) {
return {
stack: stack.slice(0, stack.length - 1),
};
}
return state;
});
});
}
render() {
return (
<View style={styles.container}>
{this.state.stack.map((scene, index) => {
const CurrentScene = scene.component;
const sceneStyles = [styles.scene];
if (index === this.state.stack.length - 1 && index > 0) {
sceneStyles.push({
transform: [
{
translateX: this._animatedValue,
}
]
});
}
return (
<Animated.View key={scene.key} style={sceneStyles}>
<CurrentScene
navigator={{ push: this.handlePush, pop: this.handlePop }}
/>
</Animated.View>
);
})}
</View>
)
}
}
const styles = StyleSheet.create({
container: {
flex: 1,
flexDirection: 'row',
},
scene: {
...StyleSheet.absoluteFillObject,
flex: 1,
},
});
Additional Challenges
Looking to further work on this example? Here's a few additional things you can work on implementing to further your experience.
- Add an overlay/shadow on the previous screen to give the appearance that the screen is behind, like iOS does
- Allow the consumer to set an initial screen via an
initialSceneNameprop rather than forcing it to be the first screen registered in theNavigatorcomponent. - Set a
backgroundColorprop to allow the consumer to set the background color for any transparent components. - Allow the consumer to swap direction of animation for right-to-left languages
- Add a swipe back gesture (interested in learning this? Check out my blog post on how to do so!)
Thanks for reading and I hope you found this exercise valuable! Whenever I want to better understanding something, or just want a code challenge, I try to find something I use often and start rebuilding it from scratch. Not only can it help you better understand what's going on but it can also help you contribute back to the open source solution you typically use!
My name is Spencer Carli - I teach people to use React Native to make their product vision a reality through online tutorials and consulting. Looking for more tutorials? Checkout my courses, tutorials, or Youtube channel!
Learn React the right way
The up-to-date, in-depth, complete guide to React and friends.
Download the first chapter