XState Docs

# Visualizer

The XState Visualizer (opens new window) is a tool for creating and inspecting statecharts to visualize the state of your applications.

As a visual tool, the Visualizer helps developers get an overview of their application logic, as well as making it easy to share and with designers, project managers and the rest of the team.

  • Write your application logic and immediately visualize it.
  • Save your statecharts to the Stately Registry and share them with anybody.
  • Share your statecharts in your team’s documentation with embedded mode and live-updating snapshot images.

The Visualizer already has many features to help you make your code do more.

# Write and visualize your code

Write and visualize your code instantly

  1. Use the code editor in the Code tab to write your machine code.
  2. Press Visualize to visualize your machine.

# Share your machines

There are multiple ways you can share your machines with your team and across the web.

Share dropdown menu with options to Copy link, Twitter, Copy image URL and Embed.

The share menu contains four options:

  1. Copy link. Copy the Visualizer URL for the machine.
  2. Twitter. Composes a tweet with a link to the machine.
  3. Copy Image URL. Copies a URL for a snapshot image of the machine.
  4. Embed. Creates an embeddable iframe containing the machine.

The Twitter link option in the share menu composes a tweet with a link to the machine’s Visualizer URL.

Composed tweet with the text “Check out the state machine I built in the @statelyai visualizer”, and a link to the machine.

# Live-updating snapshot images

The Copy Image URL option in the share menu copies the URL for the image of the machine to your clipboard. The image is a snapshot of the machine, and will update with any changes to your machine.

The image below is a snapshot of David’s example fetch machine (opens new window).

Statechart for a fetch machine.

# Embed mode

The Embed option in the share menu opens an options panel for an embeddable iframe of the machine.

Copy the code from the text area and paste it wherever you want to embed the machine. The machine can be embedded anywhere you can use iframes.

The embedded machine below is David’s example fetch machine (opens new window) in full mode with an active state panel, no link to the Visualizer, and control buttons enabled with panning and zooming both enabled:

You can choose from a number of options for your embedded machine:

# Mode option

The default mode is viz.

  • viz: Show only the Visualizer in the embedded iframe.
  • panels: Show only the Code, State, Events and Actors panels in the embedded iframe.
  • full: Show both the Visualizer and the Code, State, Events and Actors panels in the embedded iframe.

# Show control buttons option

In viz and full modes, there are further options to show the control buttons for the Visualizer. When show control buttons is selected, there are additional options to Allow panning and Allow zooming. If these options are not selected, the buttons will be visible but disabled.

# Panel options

In panels and full modes, there are further options to select the active panel, make the Editor readonly, and show the original link to the Visualizer.

# Fork existing machines

Found a useful machine in the Registry (opens new window)?

You can fork the machine, using the Fork button, and make it work for your own uses.

# Useful error messages

The Visualizer has descriptive error messages to help you understand and correct the issue when your code can’t be visualized.

Error message reading “',' expected.”. Error message reading “Invalid transition definition for state node 'fetch.failure': Child state 'load' does not exist on 'fetch'”. Error message reading “Unable to evaluate guard 'notImplemented' in transition for event in state node '(machine)': ((intermediate value)(intermediate value)(intermediate value) || t.predicate is not a function”.

The error will fade away after 4 seconds. Press Visualize to view the error again.

# Custom code editor themes

In the Visualizer’s settings you can choose from thirteen color themes for the code editor, including the default XState Viz theme.

  • Visualizer code editor with XState Viz theme.XState Viz
  • Visualizer code editor with Night Owl theme.Night Owl
  • Visualizer code editor with All Hallows Eve theme.All Hallows Eve
  • Visualizer code editor with Amy theme.Amy
  • Visualizer code editor with Blackboard theme.Blackboard
  • Visualizer code editor with Cobalt theme.Cobalt
  • Visualizer code editor with Merbivore Soft theme.Merbivore Soft
  • Visualizer code editor with Monokai theme.Monokai
  • Visualizer code editor with Tomorrow Night theme.Tomorrow Night
  • Visualizer code editor with Poimandres theme.Poimandres
  • Visualizer code editor with Garden of Atlantis theme.Garden of Atlantis
  • Visualizer code editor with Martian Night theme.Martian Night
  • Visualizer code editor with Atom One Dark theme.Atom One Dark

# How to change the code editor’s color theme

  1. Go to Settings using the button in the top menubar.
  2. Scroll down to the Editor Theme section.
  3. Choose your preferred theme from the dropdown menu.
  4. Go back to the Code view using the Code button in the top menubar.

# View controls

View controls panel featuring icons for zoom out, zoom in, fit to view, reset canvas, hand tool, and a button with reset label.

The view controls panel helps you navigate around your statechart.

  • Zoom out icon.Zoom out. Zoom out of the canvas to view more of your statechart.
  • Zoom in icon.Zoom in. Zoom into the canvas to view details in your statechart.
  • Fit to view icon.Fit to view. Fit your entire statechart into the available viewing space.
  • Reset canvas icon.Reset canvas. Reset the statechart’s position to the top left of the viewing space at 100% zoom level.
  • Hand icon.Hand tool. Select the hand tool to enter press and drag mode. Then press, hold and drag to move around the canvas. To exit press and drag mode, deselect the hand tool.
  • Reset button text.Reset button. Reset the statechart’s sequence to its initial state.

# Keyboard shortcuts and command palette

You can use keyboard shortcuts for common Visualizer commands. Find the list of Keyboard shortcuts in the Settings.

The keyboard shortcuts in the Visualizer settings.

  • CMD + S Saves or updates the code in Stately Registry (opens new window).
  • CMD + Enter Visualizes the current editor code.
  • CMD + K Show the Command palette.
  • Shift + ? Show the Command palette.

# Command palette

Use the CMD + K or Shift + ? keyboard shortcut to show the command palette. The command palette gives you quick access to common Visualizer commands.

The command palette showing commands for Saves or Updates the code in the Stately Registry and Visualizes the current editor code.

The command palette will have more commands in the future.

# And more…

  • Sign in with GitHub
  • Auto-saves locally so you won’t lose your work

# Upcoming features

We’ve got many more features coming soon. Including:

  • Support for Lucy DSL (domain-specific language)
  • Custom event and event payload support

# Get involved

Take me to the Visualizer! (opens new window)

Try the Visualizer in Inspect mode (opens new window)

The Visualizer is available now and will be free and open source forever. Contributions are welcome!

# Feedback and bug reports

If you have any feedback or have any feature requests, please join our Discord server (opens new window) where you’ll find our team and the wonderful XState community.

Please submit any bug reports as GitHub issues on the XState repository (opens new window).

Edit this page (opens new window)
Last Updated: 12/13/2021, 11:00:34 AM

Concepts →