Understanding State Machines

State machines let you define complex animation behaviors triggered by user interactions and application events. You define the logic inside your .lottie file — states, transitions, interactions, and inputs — and the player executes it at runtime.

Core Workflow

1. Define: Author your state machine in your .lottie file — states, transitions, interactions, and inputs.

2. Load animation: Instantiate the DotLottie player with your .lottie file.

3. Load state machine: After the animation loads, call stateMachineLoad with the state machine's ID.

4. Start state machine: Call stateMachineStart to make it active and responsive to events.

5. Drive inputs: Set input values or fire events from your application code to drive transitions.

6. Stop (optional): Call stateMachineStop when interactivity is no longer needed.

State Machine Structure

State machines are JSON files stored in the s/ directory of a .lottie file. The top-level structure is:

{
  "initial": "StateName",
  "states": [],
  "interactions": [],
  "inputs": []
}

States

Two state types are available:

PlaybackState — controls animation playback while the state is active:

GlobalState — overrides behaviors across all other states:

Transitions

Transitions are defined inside each state's transitions array. Two types are available:

Standard transition — immediate state change:

{
  "type": "Transition",
  "toState": "NextState",
  "guards": []
}

Tweened transition — animated crossfade over a duration:

{
  "type": "Transition",
  "toState": "NextState",
  "duration": 0.4,
  "easing": [0.4, 0.0, 0.2, 1.0],
  "guards": []
}

Transitions are evaluated in declaration order — the first matching transition fires. Tweened transitions block new state changes until the animation completes.

Guards

Guards are conditions on a transition that must all evaluate to true for the transition to fire.

Numeric guard:

{
  "type": "Numeric",
  "inputName": "score",
  "conditionType": "GreaterThanOrEqual",
  "compareTo": 10
}

Supported conditionType values: Equal, NotEqual, GreaterThan, GreaterThanOrEqual, LessThan, LessThanOrEqual.

String guard:

{
  "type": "String",
  "inputName": "mode",
  "conditionType": "Equal",
  "compareTo": "active"
}

Supported conditionType values: Equal, NotEqual.

Boolean guard:

{
  "type": "Boolean",
  "inputName": "isLoggedIn",
  "conditionType": "Equal",
  "compareTo": true
}

Event guard:

{
  "type": "Event",
  "inputName": "OnClick"
}

Event guards check whether the named event input has been fired. Events are edge-triggered and consumed after processing.

Interactions

Interactions respond to user or animation events and execute a list of actions. They are defined at the top level of the state machine, not inside individual states.

Pointer-based interactions accept an optional layerName to restrict them to a specific animation layer. OnComplete and OnLoopComplete require a stateName field.

{
  "type": "PointerEnter",
  "layerName": "button_layer",
  "actions": [{ "type": "Fire", "inputName": "OnHover" }]
}

Actions

Actions execute during interactions or in a state's entryActions/exitActions. Available action types:

Inputs

Inputs are named variables stored in the state machine. Set them at runtime to drive guard conditions.

Web Player API

Loading and Lifecycle

import { DotLottie } from '@lottiefiles/dotlottie-web';

const dotLottie = new DotLottie({
  canvas: document.querySelector('#canvas'),
  src: 'interactive.lottie',
  autoplay: false,
});

dotLottie.addEventListener('load', () => {
  const loaded = dotLottie.stateMachineLoad('myFSM');
  if (loaded) {
    dotLottie.stateMachineStart();
  } else {
    console.error('State machine not found: myFSM');
  }
});

dotLottie.addEventListener('loadError', (err) => {
  console.error('Failed to load animation:', err);
});

Always call stateMachineLoad inside the load event handler. Calling it before the animation has loaded will fail.

State Queries

Input Management

dotLottie.addEventListener('load', () => {
  dotLottie.stateMachineLoad('myFSM');
  dotLottie.stateMachineStart();

  // Set inputs before firing events to influence guard evaluation
  dotLottie.stateMachineSetNumericInput('score', 10);
  dotLottie.stateMachineSetBooleanInput('isLoggedIn', true);
  dotLottie.stateMachineSetStringInput('mode', 'active');

  const inputs = dotLottie.stateMachineGetInputs();
  console.log('Available inputs:', inputs);
});

Firing Events

Pointer interactions defined in the state machine's interactions array are handled automatically — you only need the manual Post* methods when you want to synthesize events programmatically.

State Machine Events

Listen for these events via addEventListener:

dotLottie.addEventListener('stateMachineStateEntered', (event) => {
  console.log('Entered:', event.state);
});

dotLottie.addEventListener('stateMachineTransition', (event) => {
  console.log(`${event.fromState} → ${event.toState}`);
});

dotLottie.addEventListener('stateMachineNumericInputValueChange', (event) => {
  console.log(`${event.inputName}: ${event.oldValue} → ${event.newValue}`);
});

Debugging

State machine not loading:

• Verify the ID passed to stateMachineLoad exactly matches the state machine ID in your .lottie file.

• Confirm stateMachineLoad is called inside the load event handler, not before it.

• Call stateMachineGetStatus() to inspect the current status.

Transitions not firing:

• Check that all guard conditions are met — set input values before firing the triggering event.

• Confirm stateMachineStart() was called successfully (check its return value).

• Add stateMachineStateEntered and stateMachineTransition listeners to trace execution.

Animation not playing in a state:

• Verify the animation ID in your PlaybackState matches an animation ID in your .lottie file.

• Check the segment name or frame range is valid for the referenced animation.

Related

• State Machine Examples — practical code examples for common patterns

• dotLottie 2.0 Spec — State Machines — complete format specification

• API Reference — full DotLottie class reference