react-stack-nav
v0.1.4
Published
Simple navigation for React.
Downloads
13
Readme
React stack nav
Simple universal navigation for React Native and React
- Universal Works in iOS, Android, and Web
- Familiar API Has the same API as the web's History API
- Back/forward button support Automatic support for Android back button and back/forward buttons on web
- Deep linking support Automatic support for deep linking
- Server-side rendering Simple as pre-loading redux state with the requested url
- Composable and declarative Uses React's component tree to compose and handle routes
- Use any navigation paradigm Abstract enough to let you build the navigation with any UI components you want
- Easy to understand You can read the source! Only ~300 lines of code
Examples
iOS | Android | Web :---:|:---:|:---: | Drawer example | | | | Bottom nav with stacks example | | |
The examples repo is over here.
You can also check out a real-world example in the Carbon UI Docs source.
What it looks like
A navigation component (drawer, tabs, anything):
import React from 'react'
import { Button, View } from 'react-native'
import { connect } from 'react-redux'
import { pushState } from 'react-stack-nav'
const Navigation = ({ pushState }) =>
<View>
<Button onPress={() => pushState(0, 0, '')}>Go to home</Button>
<Button onPress={() => pushState(0, 0, '/myRoute')}>Go to My Route</Button>
</View>
const mapDispatchToProps = { pushState }
export default connect(null, mapDispatchToProps)(Navigation)
A component receives and handles the first fragment of the url:
import React from 'react'
import { Text, View } from 'react-native'
import { createOrchestrator } from 'react-stack-nav'
const Index = ({ routeFragment }) =>
<View>
{routeFragment === '' && <Text>Home</Text>}
{routeFragment === 'myRoute' && <Text>My route</Text>}
</View>
export default createOrchestrator()(Index)
Installation
npm -S i react-stack-nav
Then match your redux setup to this:
import { createStore, applyMiddleware, compose, combineReducers } from 'redux'
import thunk from 'redux-thunk'
import { navigation, attachHistoryModifiers } from 'react-stack-nav'
import { BackAndroid, Linking } from 'react-native'
import app from './modules/duck'
const rootReducer = combineReducers({ navigation })
export default (initialState = {}) =>
createStore(
rootReducer,
initialState,
compose(
applyMiddleware(thunk),
attachHistoryModifiers({ BackAndroid, Linking }),
),
)
If you want deep linking to work, make sure you set it up per instructions here.
Principles
- Treat the redux store as a single-source-of-truth for routing
- Use URLs and the History API, even in React Native
- Treat the URL as a stack, and "pop" off fragments of the URL to orchestrate transitions between URLs
- Leave you in control, favor patterns over frameworks
Usage
At the core of react-stack-nav is the navigation
reducer, whose state looks like this:
{
index: 0, // The index of the current history object
history: [{ statObj, title, url }], // An ordered list of history objects from pushState
}
If you want to navigate to a new url/page, use the pushState
action creator in one of your components (it's the same as history.pushState!):
import { pushState } from 'react-stack-nav'
class MyComponent {
_handleClick = () => this.props.pushState({ yo: 'dawg' }, 'New Route', '/newRoute')
}
That'll push a new object onto state.navigation.history
, so your new navigation reducer state might look like this:
{
index: 1,
history: [
{ stateObj: {}, title: '', url: '' },
{ stateObj: {}, title: 'New Route', '/newRoute' }
]
}
Now say you clicked back in the browser (or hit the android back button), your state would automatically update to:
{
index: 0,
history: [/* same as above */]
}
With index: 0
to say, hey, we're on the first history entry.
If you want to use the history object, to ya know, render stuff, you can do so directly:
const MyComponent = ({ url, title }) =>
<View>
<Text>{title}</Text>
{url === '/users' && <UsersPage />}
{url === '/pictures' && <PicturesPage />}
</View>
const mapStateToProps = ({ navigation }) => ({
url: navigation.history[navigation.index].url,
title: navigation.history[navigation.index].url,
})
connect(mapStateToProps)(MyComponent)
You could handle all your routing like that, but...wait a minute...if you turn a url sideways, it kinda looks like a stack yeah?
/users/1/profile
users
-------
1
-------
profile
react-stack-nav
runs with this idea and introduces the idea of an orchestrator. Orchestrators pops off an element in the stack and declaratively handles transitions when it changes:
users -------> Popped off and handled by first orchestrator in component tree
-------
1 -------> Popped off and handled by second orchestrator in component tree
-------
profile -------> Popped off and handled by third orchestrator in component tree
The first orchestrator found in the component tree would handle changes to the top of the stack:
import { createOrchestrator } from 'react-stack-nav'
const Index = ({ routeFragment }) => {
<View>
{routeFragment === 'users' && <UsersIndex />}
{routeFragment === 'pictures' && <PicturesIndex />}
</View>
}
export default createOrchestrator()(Index)
The next orchestrators found in the tree would handle the next layer of the url stack, so UsersIndex
might look like this:
class UsersIndex extends Component {
async componentWillReceiveProps(next) {
const { routeFragment } = this.props
if (routeFragment !== next.routeFragment) return
this.setState({ user: await fetchUserData(routeFragment) })
}
render() {
<View>
{/* Use this.state.user info */}
</View>
}
}
export default createOrchestrator('users')(UsersIndex)
createOrchestrator()
accepts a string or a regular expression for that particular layer of that stack. If it doesn't match the current layer of the url, props.routeFragment
will be undefined.
You could create orchestrators ad inifitum all the way down the component tree to handle as much of the URL stack as you want:
const UserIndex = ({ routeFragment }) => {
<View>
{routeFragment === 'profile' && <ProfileIndex />}
{routeFragment === 'settings' && <SettingsIndex />}
</View>
}
export default createOrchestrator(/\d+/)(UserIndex)
const ProfileIndex = ({ routeFragment }) => {
<View>
{/* Would handle /users/${userId}/profile/posts */}
{routeFragment === 'posts' && <UserPosts />}
{/* Would handle /users/${userId}/profile/pictures */}
{routeFragment === 'pictures' && <UserPictures />}
</View>
}
export default createOrchestrator('profile')(ProfileIndex)
API
attachHistoryModifiers
- Store enhancer for redux, handles android back-button presses, browser back/forward buttons, and deep linkingcreateOrchestrator(fragment: string | regexp)
-- Higher-order-component that creates an orchestratornavigation
--navigation
reducer for setting up your store
Action creators
These are the same as the History API :
pushState(stateObj: object, title: string, url: string)
: Pushes a new state onto the history arrayreplaceState(stateObj: object, title: string, url: string)
: Replaces the current state on the history arrayback(reduxOnly: bool)
: Moves thenavigation.index
back one. IfreduxOnly
is true, it won't change the browserhistory
state (this is mostly for internal use)forward(reduxOnly: bool)
: Moves thenavigation.index
forward one, reduxOnly is the same as forback()
go(numberOfEntries: int)
: Moves thenavigation.index
forward/backward by the passed number (go(1)
is the same asforward()
, for example).replaceTop(stateObj: object, title: string, toUrl: string)
: LikereplaceState
, but appends thetoUrl
to the current url instead of replacing it outright. Primarily used for index redirects.pushTop(stateObj: object, title: string, toUrl: string)
: LikepushState
, but appends thetoUrl
to the current url instead of replacing it outright. Primarily used for card stacks.
Connect
Follow the creator on Twitter, @TuckerConnelly
License
MIT