react-navigation/docs/api/routers/RoutersAPI.md

## Custom Router API

You can make your own router by building an object with the following functions:

```js
const MyRouter = {
  getStateForAction: (action) => ({}),
  getActionForPathAndParams: (path, params) => null,
  getPathAndParamsForState: (state) => null,
  getComponentForState: (state) => MyScreen,
  getComponentForRouteName: (routeName) => MyScreen,
};

// Now, you can make a navigator by putting the router on it:
class MyNavigator extends React.Component {
  static router = MyRouter;
  render() {
    ...
  }
}
```

![Routers manage the relationship between URIs, actions, and navigation state](/assets/routers-concept-map.png)


### `getStateForAction(action, state)`

Defines the navigation state in response to a given action. This function will be run when an action gets passed into `props.navigation.dispatch(`, or when any of the helper functions are called, like `navigation.navigate(`.

Typically this should return a navigation state, with the following form:

```
{
  index: 1, // identifies which route in the routes array is active
  routes: [
    {
      // Each route needs a name to identify the type.
      routeName: 'MyRouteName',

      // A unique identifier for this route in the routes array:
      key: 'myroute-123',
      // (used to specify the re-ordering of routes)

      // Routes can have any data, as long as key and routeName are correct
      ...randomRouteData,
    },
    ...moreRoutes,
  ]
}
```

If the router has handled the action externally, or wants to swallow it without changing the navigation state, this function will return `null`.

### `getComponentRouteName(routeName)`

Returns the child component or navigator for the given route name.

Say a router `getStateForAction` outputs a state like this:
```js
{
  index: 1,
  routes: [
    { key: 'A', routeName: 'Foo' },
    { key: 'B', routeName: 'Bar' },
  ],
}
```

Based on the routeNames in the state, the router is responsible for returning valid components when calling `router.getComponentRouteName('Foo')` or `router.getComponentRouteName('Bar')`.

### `getComponentForState(state)`

Returns the active component for a deep navigation state.

### `getActionForPathAndParams`

Returns an optional navigation action that should be used when the user navigates to this path and provides optional query parameters.

### `getPathAndParamsForState`

Returns the path and params that can be put into the URL to link the user back to the same spot in the app.

The path/params that are output from this should form an action when passed back into the router's `getActionForPathAndParams`. That action should take you to a similar state once passed through `getStateForAction`.

### `getScreenConfig`

Used to retrieve the navigation options for a route. Must provide the screen's current navigation prop, and the name of the option to be retrieved.

- `navigation` - This is the navigation prop that the screen will use, where the state refers to the screen's route/state. Dispatch will trigger actions in the context of that screen.
- `optionName` - What named option is being fetched, such as 'title'

Inside an example view, perhaps you need to fetch the configured title:
```js
// First, prepare a navigation prop for your child, or re-use one if already available.
const childNavigation = addNavigationHelpers({
  // In this case we use navigation.state.index because we want the title for the active route.
  state: navigation.state.routes[navigation.state.index],
  dispatch: navigation.dispatch,
})
const screenTitle = this.props.router.getScreenConfig(childNavigation, 'title');
```