Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Statecharts for the rest of javascript
tree: 24343a2c35

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.

Stativus: Statecharts for the Rest of Us!

Stativus is a micro-framework that has full functionality of Statecharts for your application. It can work in any library such as:

Statecharts are a great way to organize your web application and make it more robust and increase code reuse.


Stativus comes in two versions:

  • Debug Mode: This is the file named stativus.js and it is more readable and you get the following
    • All enterState are documented with 'ENTER: state_name'
    • All exitState are documented with 'EXIT: state_name
    • All events are documented with 'EVENT: state_name fired [event_name] with n argument(s)'
    • Any time your application is configured in such a way that it will break, you will get a console or exception
    • All Async starts and stops will be outputted to the console.
    • Will warn you if you forgot to return true when using willEnterState()
  • Minified: this is the file named stativus-min.js and is a minified version for production use (gzipped: <3k)


A list of all demos can be found at Stativus Demos

You can see a working version using only HTML5 Canvas / JQuery / Stativus called RedFlix You can see the code at stativus-demo

Readings and Tutorials on Statecharts

Here are a list of resources for learning about state charts (Thanks: Johnny Luu):


To Create a Statechart, do this:

var myStatechart = Stativus.createStatechart();

Statecharts have the following functions:

  • addState
  • currentState
  • getState
  • sendEvent
  • goToState
  • goToHistoryState
  • initStates or initState
  • setData
  • getData

Statecharts also have the following functions only in Debug mode:

  • getAllStates
  • inState

Basic States should look like this:

myStatechart.addState('loading', {
  // Configuration
    globalConcurrentState: 'data_states', <= *optional: if you have more than 1 global parallel states, defaults to 'default'
    substatesAreConcurrent: true || false <= *optional: in case you have parallel substates, defaults to <false>
    parentState: 'some_parent', <= If 'null', then defaults to a top level state for the global concurrent state
    initialSubstate: 'really_loading' <= *optional: if you have substates

    // Base Events
    willEnterState: function(statechart){ ... }, <= for async coding, trigger statechart to restart with 'statechart.restart()'
    enterState: function(){ ... },
    didEnterState: function(){ ... },

    willExitState: function(statechart){ ... }, <= for async coding, trigger statechart to restart with 'statechart.restart()'
    exitState: function(){ ... },
    didExitState: function(){ ... },

    // Any other events
    doSomething: function(arg1, arg2, ...){
        // do stuff

More Advanced State can nest substates inside of them like this:

myStatechart.addState("#application", {
  initialSubstate: '#first',
  states: [ 
    { // Type 1: create configuration code as the element
      name: '#first',
      initialSubstate: '#first.first',
      states: [
        { name: '#first.first'}, // <= Multiple nesting
        { name: '#first.second'}
    ['#second', { ... config code ... }] // Type 2:  You can also pass an array where the first argument is the 
                                         // name, second argument is shared object

Async Coding can be done like this:

// Morpheus example:
myStatechart.addState("#first", {
  enterState: function(){ ... },
  testEvent: function(){

sc.addState("#second", {
  willEnterState: function(statechart){
    $('#content .boosh').animate({
      left: 911,
      complete: function () {
        statechart.restart(); // REQUIRED!!: call this function to 
                              // restart the statechart transitions
    return true; // REQUIRED!!: return true so Stativus knows to stop the 
                 // transitions and wait for animation or other async code.
  enterState: function(){ ... }


  1. Make sure that you have UglifyJS installed
  2. Clone the repository: git clone git://
  3. make



Stativus is under the MIT license that can be read in license.js Just remember who brought this to you.

Something went wrong with that request. Please try again.