Skip to documentation content

Documentation · Process

State machine

Declare the states, starting with the initial dot, then the transitions between them. A transition is labelled event [guard] / action.

Open State machine

When to use it

Describe the states an object passes through in its lifetime, the events that move it between them, and what runs on the way.

Label transitions event [guard] / action. Use a choice to branch on guards, and fork and join for regions that run at the same time.

Working example

Copy this complete example into the Source tab, then press Generate. Change its labels or values to make your first version.

Tingraph source
state "Order Lifecycle" {
  initial S0
  state NEW "Pending" {
    entry "reserveStock()"
  }
  choice C1
  state PAID "Paid"
  state SHIP "Shipped" {
    entry "notifyCustomer()"
    do "trackParcel()"
  }
  state CANCEL "Cancelled"
  final E1

  S0 -> NEW
  NEW -> C1 "pay"
  C1 -> PAID "[approved]"
  C1 -> CANCEL "[declined] / releaseStock()"
  NEW -> CANCEL "cancel / releaseStock()"
  PAID -> SHIP "dispatch"
  SHIP -> E1 "delivered"
  CANCEL -> E1
}

Syntax reference

The same reference used by the editor and AI briefing. Syntax is notation-specific; use the keywords listed here.

Diagram

SyntaxMeaning
state "Title" {open a UML state machine diagram

States

SyntaxMeaning
initial IDinitial pseudostate (filled dot); alias: start
state ID "Name"state (rounded box)
state ID "Name" { ... }state listing its internal activities
entry "action()"runs on entering, inside the block
do "activity()"runs while in the state, inside the block
exit "action()"runs on leaving, inside the block
final IDfinal state (bullseye); alias: end

Pseudostates

SyntaxMeaning
choice IDchoice (diamond): branch on guards
fork IDfork bar: one transition into several
join IDjoin bar: several transitions into one

Transitions

SyntaxMeaning
A -> Btransition with no trigger (completion)
A -> B "event [guard] / action"labelled transition, every part optional
A -> A "tick"self-transition
# commentline comment (also //)

Language rules

  • The file is one state "Title" { ... } block.
  • Start with one initial pseudostate. It leaves by exactly one transition and nothing transitions into it.
  • A final state ends the machine: no transition leaves it.
  • Label a transition "event [guard] / action"; any part may be left out, and a transition with no label fires when the state's work is done.
  • Branch on guards at a choice: one transition in, one out per guard, e.g. C1 -> PAID "[approved]".
  • A fork takes one transition in and sends several out; a join takes several in and sends one out.
  • A state's block lists entry, do and exit activities, each at most once, drawn in that order.

Edit on the canvas

  • Move and rename states on the sheet; transition labels move with their lines.
  • Draw a transition from the rail, including one from a state back to itself.

Generate replaces the drawing from source. Save before generating again if you want to preserve manual finishing touches.

Read Saving & exporting

Write it with an assistant

Tingraph AI already knows this notation. For another assistant, copy the tutorial below, describe your diagram under MY DIAGRAM, then paste the returned source into the editor. This prompt includes every syntax row, rule and working example above.

Read the complete prompt
You are writing Tingraph source. Tingraph is a small text language that draws a UML state machine diagram. Answer with Tingraph source only.

SYNTAX
Diagram
  state "Title" {             open a UML state machine diagram

States
  initial ID                  initial pseudostate (filled dot); alias: start
  state ID "Name"             state (rounded box)
  state ID "Name" { ... }     state listing its internal activities
  entry "action()"            runs on entering, inside the block
  do "activity()"             runs while in the state, inside the block
  exit "action()"             runs on leaving, inside the block
  final ID                    final state (bullseye); alias: end

Pseudostates
  choice ID                   choice (diamond): branch on guards
  fork ID                     fork bar: one transition into several
  join ID                     join bar: several transitions into one

Transitions
  A -> B                      transition with no trigger (completion)
  A -> B "event [guard] / action"  labelled transition, every part optional
  A -> A "tick"               self-transition
  # comment                   line comment (also //)

RULES
- The file is one `state "Title" { ... }` block.
- Start with one `initial` pseudostate. It leaves by exactly one transition and nothing transitions into it.
- A `final` state ends the machine: no transition leaves it.
- Label a transition `"event [guard] / action"`; any part may be left out, and a transition with no label fires when the state's work is done.
- Branch on guards at a `choice`: one transition in, one out per guard, e.g. `C1 -> PAID "[approved]"`.
- A `fork` takes one transition in and sends several out; a `join` takes several in and sends one out.
- A state's block lists `entry`, `do` and `exit` activities, each at most once, drawn in that order.

WORKED EXAMPLE
state "Order Lifecycle" {
  initial S0
  state NEW "Pending" {
    entry "reserveStock()"
  }
  choice C1
  state PAID "Paid"
  state SHIP "Shipped" {
    entry "notifyCustomer()"
    do "trackParcel()"
  }
  state CANCEL "Cancelled"
  final E1

  S0 -> NEW
  NEW -> C1 "pay"
  C1 -> PAID "[approved]"
  C1 -> CANCEL "[declined] / releaseStock()"
  NEW -> CANCEL "cancel / releaseStock()"
  PAID -> SHIP "dispatch"
  SHIP -> E1 "delivered"
  CANCEL -> E1
}

OUTPUT
- Reply with one fenced code block and nothing else.
- The block starts with `state "…" {` and ends with `}`.
- Do not invent keywords: use only the ones listed above.
- Keep labels short enough to read inside a box, and keep every ID unique.

MY DIAGRAM
Describe what you want here, then send this message.
How AI requests, attachments and privacy work

Something unclear? Contact support or read the Privacy Policy.