VERY small, full featured client-side-router (no dependencies)
Pull request Compare This branch is 693 commits behind flatiron:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


SugarSkull is a very small client side router that provides state management. What? A route is a URL and a state is the active data and appearance of the application. So when the url changes, the router performs a given task and then the application transforms, but doesn't reload the page. This is especially great for making web sites feel more responsive, like desktop apps.

  • Basic glue for building single page apps.
  • Helps clarify the code path.
  • Isolates intention (designed to separate routing from application logic).
  • Code exclusion without interference.
  • Promotes code portability.

checkout a demo here.


SugarSkull uses the HTML5 pushState API and polyfills to support older browsers. SugarSkull keeps track of what happens to the url, if the url changes, it fires off some function(s) that you have specified in the configuration.


The router takes two params...

1) A host object (optional). When it is provided, any string-literals in the route definitions will refer to members of the host-object.
2) Configuration. An object literal made up of nested regular expressions that map to functions.

Example 1: an overly simplified router

var router = SS.router({

  '/^bird/': { // the URL was either (HTML5) or
    on: birdFunction // fire a function that you created called 'birdFunction'

  '/^dog/': {
    on: dogFunction

  '/^cat/': {
    on: catFunction


Example 2: various ways to declare functions and routes

(function() {

  return {

    Main: function() {

      var router = SS.router(this, { // this example demonstrates a host object.

        '/^dog/': {
          on: 'dogFunction'

        '/^cat/': {
          on: 'catFunction'



    dogFunction: function() {
      // woof!

    catFunction: function() {
      // meow!



Example 3: a more complex configuration

var router = SS.router(someObject, {

  '/^animals\\//': {

    on: sitOnStuff, // a method defined somewhere else
    once: 'crapOnFloor', // method name called on hostobject

    '/bird[\\/]?/': {
        '/(\\w+)/': {
          on: function() {}, // perhaps an inline function?
        on: ['f1', 'f2'], // a list of methods
      state: { type: 'bird' } // the state object associated with the route

    '/dog/': {
      on: ['f1', 'f2'],
      state: { type: 'k9' }

    '/cat/': {
      on: ['f1', 'f3'],
      state: { type: 'feline' }
  '/^mamals\\//': {
    on: 'readDouglessAdams'


SS.router(host-object, config)
Initial the router.
host-object (object, optional): an object containing methods to execute. config (object, required): an object containing the router configuration.

Returns an object that is relative to the current route.

SS.setRoute(value, n, string)
Set the current route.
value ()

Returns an array that represents the current route. If an index is provided, the url (or hash depending on HTML5 pushState support) will be split into an array and the value at that index will be returned.

Returns an array that shows which routes have been retired.

  • On-Route. A list of functions to fire when the route is hit.
  • After-Route. A list of functions to fire when leaving a particular route.
  • Run-Once! Specify if the functions should be fired only once for a particular route.
  • Retire a whole route, view retired routes, and bring routes out of retirement.

  • After-All-Routes. A list of functions to fire when leaving a particular route.

  • On-All-Routes. A list of functions to fire when leaving a particular route.