Building Your Control Flow with Miso.Storyboard

Today we at the Miso Project are excited to release a new library, called Storyboard, our state management library for control flow of interactive interfaces.

As more and more of our code is written in an asynchronous manner, managing the flow of our code becomes more challenging. Event broadcasting and subscriptions is a common pattern for controling the flow of an application. Unfortunetly, that can become unmanageable and difficult to follow or debug when applications grow large.

Additionally, when thinking about interactive content, we often have multiple controls in a single interface that can be in different ‘states’. Take a common treemap control, for instance. It may be animating in or out, or may be showing a detail view rather than the entire treemap. Managing the switching in between these states often requires breaking encapsulation and intertwining controls.

Miso Storyboard offers a way to combat the aforementioned issues. Storyboard is a small library for a very simple idea: defining your application (or subset of your applications) as a set of ‘scenes’, each of which has enter and exit methods. When transitioning to a specific scene, the previous scene’s exit method is called and the next scene’s enter method gets invoked. These methods can serve as useful tools for organizing and managing your application’s state.

In practice, this allows you to define the states of your specific application separate from each other. For example, a single component might need to do a few things when it begins (such as rendering some UI and so on,) and when it’s ends (like remove loading messages). That same component can also be ‘updatingData’ or ‘showingDetails’. Either way, the enter method for each one of these scenes can set up the component state and the exit method can tear it down.

Miso.Storyboard is built on top of Underscore.Deferred, which allows your transitions to be asynchronous.

Enough talking… here’s what a storyboard might look like. Checkout the code on github and the (tiny) API on the Miso Project Storyboard site.


var interactive = new Miso.Storyboard({
  // our initial state will be loading
  initial : 'loading',

  scenes : {

    loading: {
      enter : function() {
        // show that we are in a loading state
      exit : function() {
        // This exit method is going to be asyncronous
        // so we will first declare it as such
        // by making a callback we will then need to call
        // to actually exit this scene.
        var complete = this.async();

          success : function() {

            // When our data actually loads, we can fade out the
            // loading screen (note also async!) and
            // finally call our complete method.
            $('#loading').fadeOut(function() {

    // the mainscreen scene just has our main content
    mainScreen : {
      enter : function() {
      exit : function() {

    // our details screen is for a specific element you might
    // select from the main screen
    detailScreen : {
      enter : function(datum) {
        //update the detail chart with the datum reference

// Kickoff the storyboard. It will enter the initial
// scene we specified (which is loading.)
  // when we're done loading, transition to the main screen
  .then(function() {'mainScreen');

// At some point, wire up a control to switch to the
// detail screen...
$('#mainScreen a.detail').click(function() {'detailScreen');


We moved off of Disqus for data privacy and consent concerns, and are currently searching for a new commenting tool.

  1. I love this wonderful idea and would like to use it in one of my project.

    Q1: can I use it in a proprietary/commercial project?

    Q2: notice that the project has been stale for 6 month in github. Wonder what’s the status of the project – Is it a no-good failure? or it is mature already? or just no time to maintain it?

    It would be really appreciated if you can give some light on these two questions. Thank you very much!


  2. Sijun Kang Thank you!

    1. Of course. It is under the MIT License.

    2. We’ve been maintaining the project as requests come in. We’re aware of a few folks using it and being very happy with it, but we’d love more feedback and more users.

    If you run into any issues, please feel free to email me directly (irene at or better, open tickets on the Storyboard.js github repository.

Contact Us

We'd love to hear from you. Get in touch!


P.O. Box 961436
Boston, MA 02196