node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


State Machine cat

write beautiful state charts

build status coverage report npm stable version GPLv3 licensed


Makes this


from this

doing: entry/ write unit test
       do/ write code
       exit/ ...,
# smcat recognizes initial
# and final states by name
# and renders them appropriately
initial      => "on backlog" : item adds most value;
"on backlog" => doing        : working on it;
doing        => testing      : built & unit tested;
testing      => "on backlog" : test not ok;
testing      => final        : test ok;


To enable me to make state charts ...

  • ... that look good
  • ... with the least effort possible
  • ... whithout having to interact with drag and drop tools. Entering text is fine, doing my own layout is not.
  • ... without having to dive into GraphViz dot each time. GraphViz is cool, but is was not designed to write & maintain conceptual documents in (You'll know what I'm talking about if you ever tried to get it to draw nested nodes. Or edges between those. )


On line

A no-frills interpreter on line:

Within the Atom editor

There's an Atom package with syntax highlighting, a previewer and some export options. You can install it from within Atom (search for state machine cat in the install section of the settings screen) or use apm i state-machine-cat-preview if you're a command line person.

OTOH. if you're a command line person the command line interface might be something for you too:

Command line interface

Just npm install --global state-machine-cat and run smcat

This is what smcat --help would get you:

Usage: smcat [options] [infile]


  -V, --version            output the version number
  -T --output-type <type>  smcat|dot|json|ast|svg|html|scxml|scjson (default: svg)
  -I --input-type <type>   smcat|json (default: smcat)
  -E --engine <type>       dot|circo|fdp|neato|osage|twopi (default: dot)
  -d --direction <dir>     top-down|left-right (default: top-down)
  -o --output-to <file>    File to write to. use - for stdout.
  -l --license             Display license and exit
  -h, --help               output usage information

... so to convert the above chart to sample.svg

bin/smcat docs/sample.smcat

Or, if you'd rather have the native GraphViz dot do that for you:

bin/smcat -T dot docs/sample.smcat -o - | dot -T svg -odoc/sample.svg

Leaving the options at the default settings usually deliver the best results already, so if they bewilder you: don't worry.

State chart XML (SCXML)

state machine cat can emit a valid core constructs scxml document. If you're into that sort of thing you can read all about it in State Machine Cat and SCXML.


After you npm i 'd state-machine-cat:

const smcat = require("state-machine-cat");
try {
    const lSVGInAString = smcat.render(
            initial => backlog;
            backlog => doing;
            doing => test;
            outputType: "svg"
} catch (pError) {

Read more in docs/

The language

Short tutorial


on => off;
  • smcat automatically declares the states. You can explicitly declare them if you want them to have more than a name only - see explicit state declarations below.


on => off: switch;

UML prescribes to place conditions after events, to place conditions within squares and to place actions after a /: from => to: event [conditions]/ actions, e.g. on => off: switch flicked [not an emergency]/ light off;.

You're free to do so, but smcat doesn't check for it. It internally takes the notation into account, though and if you choose to export to json, scxml or scjson you'll see them nicely split out.

on => off: switch flicked/
           light off;
off => on: switch flicked/
           light on;

You note that smcat rendered the states in this chart top down instead of left to right. It did that because we told it so. You can do that too with --direction on the command line, or in atom by direction -> left to right or direction -> top down from the chart's submenu.


# this is a note
on => off;

explicit state declarations

# yep, notes get rendered here as well
# multiple notes translate into multiple
# lines in notes in the diagram
doing: pick up

initial and final

When initial or final, is part of a state's name smcat treats it as the UML 'pseudo states' initial and final respectively:

initial => todo;
todo    => doing;
doing   => done;
done    => final;


smcat recognizes states with history in their name als history states:

"power off",
running {  
  washing -> rinsing: 20 min;
  rinsing -> spinning: 20 min;
  spinning -> final: 20 min;
initial => washing;
running => "power off": power out;
"power off" => running.history: restore power;

Choice - ^

smcat treats states starting with ^ as UML pseudo state choice. Strictly speaking 'choice' is a superfluous element of the UML state machine specification, but it is there and sometimes it makes diagrams easier to read.

^fraud?: transaction fraudulent?;
initial -> reserved;
reserved -> quoted:
quoted -> ^fraud?: payment;
^fraud? -> ticketed: [no];
^fraud? -> removed: [yes];
ticketed -> final;
removed -> final;

Forks and joins - ]

In UML you can fork state transitions into multiple or join them into one with the fork and join pseudo states. Both of them are represented by a black bar. To make a join or fork pseudo state, start its name with a ]. Here's an example of a join:

a => ]join;
b => ]join;
]join => c;


  • when you need ;, ,, { or spaces as part of a state - place em in quotes "a state"
  • Activities have the same restriction, except they allow spaces.
  • Labels have the same restriction as activities, except they allow for , too.
  • State declaration precedence is: deep wins from shallow; explicit wins from implicit
  • It's possible to declare the same state multiple times on the same level, buts smcat will take the last declaration into account only. For example:


# first declaration of "cool state"
"cool state",
"other state",
# second declaration of "cool state"
"cool state": cool down;

results in (/ is equivalent to):

# second declaration of "cool state"
"cool state": cool down,
"other state";

nested state machines

It's possible to have state machines within states. the states stopped, playing and pause can only occur when the tape player is on:

"tape player off",
"tape player on" {
  stopped => playing : play;
  playing => stopped : stop;
  playing => paused  : pause;
  paused  => playing : pause;
  paused  => stopped : stop;

initial           => "tape player off";
"tape player off" => stopped           : power;
"tape player on"  => "tape player off" : power;



I made the parser with pegjs - you can find it at src/parse/peg/smcat-parser.pegjs


  • Thoroughly tested and good enough for public use.
  • Despite this you might bump into the occasional issue - don't hesitate to report it, either on GitLab or on GitHub.
  • Runs on latest versions of firefox, safari and chrome and node versions >= 6. Although it might run on other environments, it's not tested there. I will reject issues on these other environments, unless they're accompanied with sufficient enticement to make it worth my while.