Skip to content

Latest commit

 

History

History
149 lines (97 loc) · 5.47 KB

routing.md

File metadata and controls

149 lines (97 loc) · 5.47 KB
Raw

Routing

Routing components that allow you to implement single page app routing functionality.

Reference:

Usage

import {Router, Match, Route, Switch, go, Link, createRouter} from 'libreact/lib/route';

Use any state container

With libreact's <Router> you can choose to store the current route in your state continer (like Redux or MobX). The "problem-of-all-routers" is that they all want to keep the state of the route. For example, react-router uses its internal history objects to store route information, and it does not give you good access to that data structure.

So, if you wanted to store the state of the route in Redux, there was no good way for you to do that using react-router, that is why redux-little-router was born, however, redux-little-router itself hoards the state of the route in Redux, so you cannot use it if you use any other state container, say MobX.

Libreact is completely orthogonal to where you store the current route, all you have to do is provide the current route to the <Router> component using the route prop.

<Router route={currentRoute}>
  {/* ... */}
</Router>

You can store it in Redux or MobX, or really anywhere you want. And if you don't want to bother, don't! Just use the current location of the browser:

<LocationSensor>{({pathname}) =>
  <Router route={pathname}>
    {/* ... */}
  </Router>
}</LocationSensor>

Multiple routers

You can have many routers operating on the same page in parallel. All you have to do is specify a namespace using the ns prop.

<Router ns='secret'>
  <Route ns='secret' />
</Router>

Or use createRouter() to create React components with bound namespace.

Reference

<Router>

Router is a root component that provides routing to your application. It should be placed above all other components that use routing. It uses React's context Provider component to provide route information to its children.

Props

  • route — required, string, route to use for routing. If not specified, <Router> will use
  • ns — optional, string, namespaces of the router. This allows you to have many different routers on one page, each in a separate namespace.

Unlike in other routing libraries <Router> component forces you specify the current route manually using the route property, this way you can use Redux or MobX, or any other state container library to store your route.

<Route>

Route tries to match a fragment in a route. If it does match, the contents of the route is rendered. The contents of the route can be either regular JSX children or a FaCC, render prop, or component prop.

Props

  • match — optional, matching condition, defaults to empty string. This can be a regular expression.
  • exact — optional, boolean, whether string route has to match exactly.
  • truncate — optional, boolean, whether matched part of the route should be truncated for the nested routes.
  • ns — optional, string, namespace of the router.

match prop can be a string, RegExp of a Function.

  • if string, it is converted to a regular expression with ^ prepended, which means it has to match the route starting from the very first character. For example, /users -> /^(\/users)/. If the exact prop is on, also $ appended to the regular expression, which means the regular expression has to match the route exactly. For example, /users -> /^(\/users)$.
  • if RegExp, the specified regular expression will be used to match the current route, the resulting matches array will be returned, if any.
  • if Function is provided, it has to return an array of strings on a match.

<Match>

<Match> component is similar to <Route>, but it always renders its children, regardless if route was actually matched.

go()

Utility function that changes the current browser location. Has the following signature:

go: (url: string, params?: IGoParams) => void;

interface IGoParams {
  replace?: boolean;
  title?: string;
  state?: any;
}
  • url - required, string, URL where to navigate the browser. Usually you want to use a relative route with leading slash, like /users.
  • replace - whether to to use .replaceState() rather than default .pushState() when invoking History API.
  • title - title to specify in .pushState() or .replaceState() methods.
  • state - any serializable JavaScript object to store with the current history state. Useful, for example, to store current scroll position.

<Link>

Renders a link that will change browser location on click.

createRouter()

Create a new collection of router components given a namespace.

const {Router, Route, Match} = createRouter('inner-router', go);