Skip to content
Version: XState v4


Annotations are notes you can use to annotate your machine, positioned anywhere inside your machine. Annotations are useful for information or comments you want to add to your machine that are only visible inside Stately Studio and not included when you export as code.

Unlike descriptions, annotations don’t need to be connected to a state or transition and can be added or positioned anywhere inside your machine.

Add annotations to your machine​

You can add annotations anywhere on your machine from Design and Simulate mode, but you can only edit them in Design mode.

Annotations are unrelated to a state or transition. Still, their layout position is connected to the closest root or parent state when you create them, which helps give your annotations enough space in the auto layout.

  1. Right-click anywhere on the canvas to open the canvas menu.
  2. Choose Add annotation to create a new annotation on the canvas.
  3. Type your annotation text into the annotation.

Edit annotations​

  • Select an annotation to edit it, then click inside the annotation to edit its text.
  • Select and drag an annotation to change its position on the canvas.

Delete annotations​

  • Select an annotation to edit it, then use backspace to delete the annotation.
  • Right-click on an annotation to open the Delete option menu, then use Delete to delete the annotation.