Skip to content
Version: XState v4

Version history

Version history is helpful if you want to save checkpoints while modeling machines or mirror version changes in the rest of your codebase. New versions can be saved from the current machine using the Version history panel in the right tool menu when in Design mode.

All users can view versions of public machines. Users on our Pro plan and team members can view and create versions for machines in team projects and their own machines in My Projects. Read more about team roles and versions.

Save a version

You can save a new version of your machine when in Design mode.

  1. Open the Version history panel from the right tool menu.
  2. The Current version of the machine is selected by default. Use the Save button to create a new version from your current machine.

Versions are named with their creation time by default and have the version creator’s avatar.

Version history panel opened from the right tool menu showing a list of versions.Version history panel opened from the right tool menu showing a list of versions.

Rename a version

You can rename any version to something other than the version’s timestamp.

  1. Select the version name to reveal the text input.
  2. Enter the version’s new name.
  3. The new name will be autosaved when you hit enter or navigate away from the text input.

Selecting a version name in the Version history panel, showing the text input for the new name.Selecting a version name in the Version history panel, showing the text input for the new name.

The version’s timestamp will still be shown under the version name.

Auto-saved versions

There are some cases where versions will automatically be created for a machine Auto-saved versions are indicated in the list of versions with the Stately bot icon.

Initial versions

An initial version is automatically saved for new machines when:

  • you fork a machine from an existing machine or project
  • you duplicate an existing machine in its project

These versions are labeled “Initial version”.

Periodic snapshot versions

To reduce the likelihood of data loss, versions are automatically saved hourly (approx.) as long as edits have been made to the project machine. These versions are labeled with a timestamp, and these labels can be edited. They work just like other versions that you can view, restore, or delete.

In the version list, these auto-saved versions are hidden by default but you can toggle their visibility to show them along with versions you explicitly save.

View a version

You can view any version by selecting that version in the Version history. The version will be shown in the Editor and read-only unless you restore that version using the Restore button.

A version previewed in the Editor which highlights the top bar to show you’re in preview mode.A version previewed in the Editor which highlights the top bar to show you’re in preview mode.

You can return to viewing the current version of your machine from Return to current version in the top bar or by selecting Current Version from the Version history in the right tool menu.

Restore a version

You can restore your current machine to any version from the version history.

Restore a version from the Version history panel

  1. Open the Version history panel from the right tool menu.
  2. Hover over the version you want to restore to reveal the restore icon button.
  3. Use the restore icon button to restore to your chosen version.

Version history panel with the restore icon revealed on hover.Version history panel with the restore icon revealed on hover.

Restore a version when viewing a version

When viewing a version, you can restore to that version using the Restore button in the top bar.

A version previewed in the Editor with an arrow pointing to the Restore button.A version previewed in the Editor with an arrow pointing to the Restore button.

Create a new machine from a version

You can also create a new machine from a version in your version history.

  1. Open the Version history panel from the right tool menu.
  2. Select the version from which you want to create a new machine. The version will be previewed in the Editor.
  3. Use the copy icon button in the top bar to create a new machine from that version.

A version previewed in the Editor with an arrow pointing to the Copy button.A version previewed in the Editor with an arrow pointing to the Copy button.

Your new machine will be created and opened in the same project with the same name appended with “(copy).”

Delete a version

  1. Open the Version history panel from the right tool menu.
  2. Select the version you want to delete. The version will be previewed in the Editor.
  3. Use the delete icon button in the top bar to delete that version.
  4. The current version will then be opened in the Editor.

A version previewed in the Editor with an arrow pointing to the Delete button.A version previewed in the Editor with an arrow pointing to the Delete button.

Team roles and versions

All team members can view past versions of machines in their team’s projects. Team owners, Admins, and Editors can also create and restore versions. Only Owners and Admins can delete versions.

CapabilityOwnerAdminEditorViewer
View team machine versions Yes Yes Yes Yes
Create new versions of team machines Yes Yes Yes Yes
Restore versions of team machines Yes Yes Yes🚫 No
Delete versions of team machines Yes Yes🚫 No🚫 No