jdlehman/jsrouter

Minimal client side router

jsrouter

jsrouter is a minimal client side router based on window.location.hash. It utilizes route-recognizer to match routes and leans on this library for the API as well. For this reason, you will notice that the API is very similar to Ember's router, though more minimal and with less lifecycle states.

Installation

npm

npm install --save jsrouter

cdn

While the npm package is recommended for production usage, if you just want to drop a <script> tag on your page you can also use the UMD/global build hosted on unpkg.

<script src="https://unpkg.com/jsrouter@1.0.0"></script>

Usage

This is to provide a good idea of what the API looks like and what jsrouter can do. Check out the documentation for more details as well as an in depth breakdown of the API.

Create the router

import Router from 'jsrouter';

// create a new router
var router = new Router();

Define routes

// define routes
router.map(function(match) {
  match('/').to('home'); // where "/" is the route and "home" is the handler name
  match('/signup').to('createAccount');
  match('/signin').to('login');
  match('/profile/:id').to('profile'); // where id is a dynamic route segment
  match('/parent').to('parent', function(match) { // nested routes
    match('/child').to('child', function(match) { // matches /parent/child and calls both handlers
      match('/*splat').to('everythingElse'); // "*splat" will match everything
    });
  });
});

In depth documentation

Define handlers

// define handlers
router.addHandler('home', {
  // enter/leave called when route is entered and left
  enter: function({path, lastPath, queryParams, params}) {
    // path === current path
    // lastPath === last path
    // queryParams === query parameters
    // params === dynamic matched segments or splats
  },
  leave: function({path, nextPath, queryParams, params}) {
  }
});
// etc...

In depth documentation

Using the router

// using the router
router.navigate('/');
router.navigate('/signup', {promo: 'test'}); // optionally takes data to store in window.history.replaceState
router.navigate('/profile/1');

router.back(); // window.history.back();
router.forward(); // window.history.forward();

In depth documentation

Configuration

The router takes an optional object as an argument that allows it to override default configuration and customize the behavior of the router.

var router = new Router({
  unrecognizedRouteHandler: function() {
    router.navigate('/notFound');
  },
  handleBeforeChange: function({path, string, queryParams, params}) {
    // do not change routes if this returns false
  },
  // ...
  // etc.
});