---
title: "States"
description: "Choose which stretch of an animation plays in response to a press, a hover or a value from an app."
canonical: "https://terminal.lottiefiles.com/docs/states/"
last_updated: 2026-10-28
---

# States

Choose which stretch of an animation plays in response to a press, a hover or a value from an app.

A state machine connects named states with rules. Each state plays a marker's stretch of the
score (the timeline), or holds a pose. The graph shows the states as cards and rules as arrows.
See [Motion and interactivity](https://terminal.lottiefiles.com/docs/concepts/motion-and-interactivity.md) for how they fit together.

## Open and start

Press `⌃T`, click **◇** under the stage, or run **State machines** in the command palette
(`:`). The graph takes most of the screen. The stage sits beside it, an inspector below the
stage, and the markers' lane below the graph.

With no machine, choose **+ a state for each marker** to use the document's markers. The first
marker's state is the start. **+ start with one state** makes **idle**, playing everything.

![Two states connected by press button and ends rules, with pulse's settings beside the graph.](https://terminal.lottiefiles.com/docs/assets/shots/more-state-button-rules.png)

## Graph and toolbar

| Control or action | What happens |
|---|---|
| Machine name | Click to rename the machine. |
| **◂** **▸** | Select another machine in the file. The counter shows which is open. |
| **start this one** | Make the selected machine the one players start. Shown when it is not already the initial machine. |
| **+ new** / **delete** | Add or remove a machine. `u` brings a deleted machine back. |
| **+ state**, or `n` | Name a new state. A marker's name makes it play that marker; with a loop set, a new marker spans the loop. |
| **⤢ fit**, or `f` | Fit the whole graph in view. |
| **tidy** | Lay out the cards again. `u` restores your arrangement. |
| **▶ try** / **■ stop** | Start or stop trying the machine. `space` does this while the graph has the keys. |
| **done ✕**, or `⌃T` | Return to the editor. |
| Click a card | Select its state and show its settings and rules. While trying, force the player to that state. |
| Double-click a card | Rename it. |
| Drag a card | Move it; its position stays with the file. |
| Drag from a card's **●** to another | Add a rule between them; type what sets it off. |
| Drag from **●** to empty canvas | Name a new state there, then add the rule. |
| Double-click empty canvas | Name a new state there. |
| Click an arrow | Show its rules in the inspector. Several rules between the same states share an arrow. |
| Drag empty canvas, scroll, or `←` `↑` `→` `↓` | Move around the graph. |
| `⇥` / `⇧⇥` | Select the next or previous state. |
| `⌫` / Delete | Delete the selected arrow's rule or selected state. Deleting a state also removes rules going to it. |
| `esc` | Cancel typing, then clear the selected arrow or state, then leave the mode. You may need more than one press. |

The incoming arrow marks the start. **any state** holds rules that apply wherever the machine
is. Cards show their marker, looping or holding, and entry actions. Backward arrows go round
the graph. Long arrow labels are shortened; click one to read the complete rules.

## A state's inspector

Select a card to see **STATE**. Click a value to change it; `⏎` keeps typed text and `esc`
cancels. Each change is one undo step (`u`; `⇧U` restores it).

| Control | Values and meaning |
|---|---|
| State name | Click the selected state's name to rename it. **✕** deletes it. |
| **plays** | Pick or type a marker, or choose **all** for the whole animation. |
| Time range | The marker's start and end in seconds (`0.5–1.2`) or frames (`15f–36f`). Changing a shared marker affects every state that plays it. A missing marker says **no such marker**. |
| **← the loop** | Set the marker's stretch to the editor's loop (`b` and `n` set its ends in the editor). |
| **▶ plays** / **❚❚ holds** | Play on entry, or hold the first frame. |
| **⟳ loop** | Repeat the stretch. |
| **×∞** / **×2** | Loop count. Empty or 0 means for ever; a positive whole number ends after that many loops. Appears when looping is on. |
| **→**, **←**, **⇄**, **⇆** | Forward, reverse, bounce, reverse bounce. Click to cycle. |
| **1×** | Positive playback speed; 1 is the keyed speed, 2 twice as fast. Use reverse mode to play backwards. |
| **■ ends it** | Entering this state ends the machine. |
| **bg ·** / **bg #rrggbb** | Background colour: `#rgb`, `#rrggbb` or `#rrggbbaa`. Empty or `none` clears it. |
| **anim ·** / **anim** followed by an id | Which animation in a multi-animation `.lottie` it plays. Appears when more than one is available. |
| **◉ start** | Start the machine in this state. Appears on states that are not the start. |
| **+ rule**, or `⏎` with a state selected | Add a rule under this state. |

## Rules

Click a rule to edit it. Suggestions offer layers, states, inputs and words the rule accepts.
Use `↑` `↓` to pick a suggestion and `⇥` to insert it, or click it. `⏎` accepts a selected
suggestion, or keeps the line when none is selected. **✕** removes a rule.

A transition uses `→`; an action uses `:`. Names with spaces can be quoted. A line can create
the inputs, events and states it names. Read the line back to check what was kept.

| Line | Meaning |
|---|---|
| `press button → pressed` | Pointer down on layer button. Without a layer, anywhere. |
| `release button → idle` | Pointer up. |
| `click button → pressed` | Click on the layer. |
| `hover button → hover` | Pointer enters the layer. |
| `leave button → idle` | Pointer leaves the layer. |
| `move: n = 1` | Pointer movement triggers an action. |
| `ends → idle` | The state's stretch finishes. An endless loop does not finish. |
| `loops → pulse` | One more loop finishes. |
| `on submit if stars ≥ 3 → thanks` | Event submit fires and stars is at least 3. |
| `stars ≥ 5 → winner` | Move as soon as the condition holds. |
| `then → idle` | Move without a condition. |
| `enter: n = 0` / `exit: n + 1` | Actions on entering or leaving this state. |
| `press star3: stars = 3` | Under **ANY STATE**, a press changes a value wherever the machine is. |
| `hover button → hover over 0.25s out` | Blend to the other state over a quarter of a second. |

Rules are tried in order. **ANY STATE** transitions are tried before the current state's.
Conditions joined with `and` must all hold. Use `=`, `≠`, `>`, `≥`, `<`, `≤` for numbers;
text and Booleans compare with `=` or `≠`. Use `enabled` or `not enabled` for a Boolean input,
quoted text for strings, `$other` for another
input's value, and `elapsed` for seconds since the machine started. `on submit` refers to an
event, not a Boolean value.

| Action | Meaning |
|---|---|
| `n + 1`, `n - 1`, `n × 2` | Add, subtract or multiply. |
| `n = 3`, `enabled = true`, `label = "ready"` | Set a number, Boolean or text. `$other` copies an input's value. |
| `n = random 0..1`, `n = random int 1..6` | Random number or integer in a range. |
| `toggle enabled` | Switch a Boolean value. |
| `reset n` | Restore its starting value. |
| `floor n` | Round down. |
| `clamp n 0..5` | Keep the number within the range. |
| `fire go` | Fire an event input. |
| `theme dark`, `theme $choice`, `theme none` | Set a theme by id, read its id from an input, or clear it. |
| `frame 30` | Go to a frame. |
| `progress 50%` | Go to a percentage of the animation. |
| `emit "done"` | Send a custom event for the host app to hear. |
| `open https://example.com in _blank` | Request a URL and target after a press. The host app must allow that URL. |

Separate several actions with commas: `enter: likes + 1, emit "favourited"`.
Blends accept seconds or milliseconds and an ease preset, or `[x1, y1, x2, y2]`.
Presets are `linear`, `ease`, `in`, `out`, `in-out`, `expo-out`, `back-out`, `anticipate`
and `snap` (see [Editing](https://terminal.lottiefiles.com/docs/editing.md)).

## Inputs

**INPUTS › + add** accepts a name and starting value: `n = 0`, `enabled = false`,
`label = "ready"`, or `go` for an event. The type is number, Boolean, text or event.

Click an input's name to rename it; rules follow the new name. Click a value to set its
starting value while editing, or its current value while trying. **⚡ fire** fires an event.
An input's **✕** appears on hover and deletes it only when no rule uses it. Rest the pointer
on a value to see the corresponding player call, such as
`dotLottie.stateMachineSetNumericInput("likes", 3)`.

## Try it

Press `space` in the graph, or `⌃P` from the editor. **▶ try** under the stage does the same.
The stage becomes the player: clicks and hovers interact rather than edit. The active state
and the arrows it takes light up. **WHAT HAPPENED** records transitions, changed inputs and
events. Click a card to force a state; edit an input to act as the host app.

**show targets** toggles outlines. They start hidden; interaction works either way. `r`
restarts with the initial inputs. `esc`, `space`, `⌃P` or **■ edit** returns to editing;
the graph toolbar also has **■ stop**. Returning restores the editor's stage.

![The button being tried, with pulse active after a press and the event recorded below.](https://terminal.lottiefiles.com/docs/assets/shots/more-state-button-trying.png)

From the editor, the left panel and most of the score step aside while you try the machine.
The ruler and markers remain. Blends, themes, state backgrounds and other animations in the
same `.lottie` play on the stage. Editing a machine while trying keeps its current state where
possible. Undo, save, help and the copilot remain available.

## Markers and checks

The lane under the score's ruler shows markers. Drag an end to resize a stretch, its middle
to move it, or empty lane to draw a new stretch and name its state. Double-click a marker to
loop its stretch in the editor.

**CHECK** lists findings with their source. Click one to show it. It checks these cases:

| Kind | What it catches |
|---|---|
| Machine and names | An unreadable machine, no states, a missing initial or destination state, a transition into **any state**, missing inputs, animations, markers, layers or themes. |
| Playback and rules | An immediate exit, an endless loop with `ends`, `loops` on a state that does not loop, or an ending that cannot happen in the state listening for it. |
| Blends | A blend landing at or past the source stretch's end, where its `ends` or `loops` rule may run first or again. |
| Input actions | An unused input, an unknown input reference, a comparison that cannot hold, resetting an event, resetting on initial entry before the player is running, or a clamp with no bounds. |
| Reachability | A state no rule goes to, or an immediate cycle that makes the player stop after more than 20 transitions. |
| URLs | Opening a URL requires a press and the host app's permission. |

A check helps find mistakes; test the actual presses and input changes too.

Two examples, on home or by name in the palette, are machines to try: **States**, a favourite
button (hover, press, liked, unlike), and **Checkout**, a pay button that waits for the app's
answer while a spinner loops. Its **auto** input answers for the app; turn it off and type
`ok` or `declined` into **result** yourself.

## Save and use in a player

Save or export a `.lottie` to carry the machine to a dotLottie player with state-machine
support. A file can hold several machines; **start this one** chooses the one players start.
A JSON file keeps them for this app only: export a `.lottie` for players.
Rive machines can also be opened and tried; see [Layers](https://terminal.lottiefiles.com/docs/layers.md).

Read a file's machines from a shell:

```sh
creator-tui states button.lottie
creator-tui states button.lottie --json
```

The first prints rules, player calls and checks. The second prints dotLottie JSON.
The copilot's `states` tool can list and edit rules, states, inputs, markers and machines,
check them, replace machine JSON, or try a sequence of interactions.

Next: [Make a button react to a press](https://terminal.lottiefiles.com/docs/how-to/make-a-button-react-to-a-press.md).
Watch: [State machines](https://terminal.lottiefiles.com/state-machines/).