Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/expo/ex-navigator
Route-centric navigation built on top of React Native's Navigator
https://github.com/expo/ex-navigator
Last synced: 7 days ago
JSON representation
Route-centric navigation built on top of React Native's Navigator
- Host: GitHub
- URL: https://github.com/expo/ex-navigator
- Owner: expo
- License: mit
- Created: 2015-07-01T20:58:27.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2018-02-17T05:18:34.000Z (almost 7 years ago)
- Last Synced: 2024-11-30T17:05:07.503Z (14 days ago)
- Language: JavaScript
- Homepage:
- Size: 74.2 KB
- Stars: 522
- Watchers: 41
- Forks: 68
- Open Issues: 21
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-react-native - ex-navigator ★531 - Route-centric navigation built on top of React Native's Navigator (Components / Navigation)
README
# ExNavigator
> **Deprecation Warning** There are a few bugs in ex-navigator that
require mutation of the state for the state to pass through the
Navigator [[Issue
110](https://github.com/expo/ex-navigator/issues/110)]. ~It's
highly recommended to use the new
[ex-navigation](https://github.com/expo/ex-navigation) instead as
it's a powered by React Native's "NavigationExperimental".~ It's
recommend to use
[react-navigation](https://github.com/react-community/react-navigation)
instead.
ExNavigator is a scene navigator that is centered around routes and is built on top of React Native's Navigator. You define ExRoutes, which are plain JavaScript objects with functions to render the scene for the route and the components to display in the nav bar.
The API is in ExRoute.js and ExRouteRenderer.js.
Otherwise ExNavigator is very similar to Navigator.
## Why?
[This post](https://medium.com/the-exponent-log/routing-and-navigation-in-react-native-6b27bee39603#.13j2waolq) explains the ideas that are in ExNavigator and how we use it so you can assess whether it is useful for your project, too.
## Installation
```
npm install @expo/react-native-navigator --save
```
ExNavigator is compatible with React Native 0.16 and newer.
## Example projects
Github user [Thorenandresen](https://github.com/Thorbenandresen) has two very simple bare bones projects showing ExNavigator in use:
* [ExNavigatorExample](https://github.com/Thorbenandresen/ExNavigatorExample)
* [ExNavigatorExampleModal](https://github.com/Thorbenandresen/ExNavigatorExampleModal)
## Usage
ExNavigator's component API looks very similar to Navigator's. You specify a `routeStack` and/or `initialRoute`, along with some styles. ExNavigator will render the navigation bar for you and accepts some props to style its contents. See `ExNavigator.propTypes` for the list of accepted props.
**You must use JavaScript's `import` keyword to import ExNavigator. Do not use `require()`.**
```js
import ExNavigator from '@expo/react-native-navigator';
class Example extends React.Component {
render() {
return (
);
}
}
```
### Routing
The main difference between ExNavigator and Navigator is what the route objects look like. With ExNavigator, you define what each scene looks like, what its navigation bar's contents should be, and what to do when the scene gains or loses focus. A common pattern is to define a router where you create routes:
```js
let YourRouter = {
getHomeRoute() {
return {
// Return a React component class for the scene. It receives a prop
// called `navigator` that you can use to push on more routes.
getSceneClass() {
return require('./HomeScene');
},
// When this scene receives focus, you can run some code. We're just
// proxying the `didfocus` event that Navigator emits, so refer to
// Navigator's source code for the semantics.
onDidFocus(event) {
console.log('Home Scene received focus.');
},
// Return a string to display in the title section of the navigation bar.
// This route's title is displayed next to the back button when you push
// a new route on top of this one.
getTitle() {
return 'Home';
},
};
},
getProfileRoute(profile) {
return {
// You can also render a scene yourself when you need more control over
// the props of the scene component
renderScene(navigator) {
let ProfileScene = require('./ProfileScene');
return ;
},
// There are onWillBlur and onDidBlur events when the scene loses focus.
// These events occur when another scene will focus or did focus,
// respectively. The difference between "will" and "did" is the start and
// end of the scene transition.
onDidBlur(event) {
console.log(`Profile Scene for ${profile} lost focus.`);
},
// You can render arbitrary views for the title component. Note that you
// also need to implement getTitle if you want the title of this route to
// show up in the back button to it.
renderTitle() {
return (
{profile.name}
);
},
getTitle() {
return profile.name;
},
// Render the view to display on the right side of the navigation bar. It
// is typically a button but doesn't have to be.
renderRightButton() {
return (
{ console.log('Tapped right button'); }}>
Log
);
},
};
},
};
```
### Navigating
To navigate to a new scene, you use an API very similar to Navigator's. Create a route object—perhaps with the help of your router—and give it to the ExNavigator:
```js
class HomeScene extends React.Component {
render() {
return (
{
// Get a route object from the router
let profile = {
name: 'Alex',
photoUrl: 'https://images.example.com/alex.jpeg',
};
let route = YourRouter.getProfileRoute(profile);
// `navigator` is passed into your scene component when you have
// implemented getSceneClass in your route
this.props.navigator.push(route);
}}>
Navigate to a profile
);
}
}
```
### iOS Scene Transition Shadow
The default scene config, `FloatFromRight`, has the ability to display a shadow just like it does natively on iOS. However, you need to define your own shadow. Add the following styles in the `sceneStyle` property on your `ExNavigator` component:
```
sceneStyle={{
overflow: 'visible',
shadowColor: '#000',
shadowOpacity: 0.5,
shadowRadius: 6
}}
```
### Flux-based navigation
You can use the ExNavigator routing framework using Actions to change the route instead of passing around a navigator. [react-native-router-flux](https://github.com/aksonov/react-native-router-flux) is built on top of ExNavigator.