Core Concepts: Managing State Machines

State Machines, a V2 feature in dotLottie, enable interactive Lottie animations. Define states, transitions, and event listeners to control animation playback based on user input or events. dotlottie-js packages these configurations within the .lottie file.

What are State Machines in dotLottie?

A State Machine defines the logic for interactive animation playback. It consists of:

States: Represent specific points or segments within an animation (e.g., "Play Loop", "Stop", "Hover Segment").
Transitions: Define how to move between states based on events (e.g., "On Click", "On Hover", "On Animation Complete").
Listeners: Trigger transitions based on events.
Initial State: The state the animation starts in.

This logic is typically defined in a JSON format compatible with the target dotLottie player. Find the specification at dotlottie.io/docs/state-machines.

dotlottie-js allows you to add these State Machine JSON definitions to your .lottie file.

1. Adding State Machines: `dotlottie.addStateMachine()`

Use the dotlottie.addStateMachine() method.

import { DotLottie } from "@dotlottie/dotlottie-js";

async function main() {
  const dotlottie = new DotLottie();

  // Example State Machine JSON (structure defined by the dotLottie spec)
  const stateMachineData = {
    descriptor: {
      id: "sm_toggle", // ID within the state machine data itself
      initial: "state_off",
    },
    states: {
      state_off: {
        animationId: "anim_toggle", // Animation this state controls
        on: [{ event: "onClick", transitionTo: "state_on" }],
      },
      state_on: {
        animationId: "anim_toggle",
        segment: [10, 20], // Play a specific segment
        on: [{ event: "onClick", transitionTo: "state_off" }],
      },
    },
  };

  dotlottie.addStateMachine({
    id: "sm_toggle_main", // Required: Unique ID for this state machine in the .lottie
    data: stateMachineData, // Required: The state machine JSON data
    name: "Toggle Button Logic", // Optional
  });

  console.log("State machine added.");

  // Remember to build!
  // await dotlottie.build(); See the DotLottie Instance page for details.
}
main();

Key addStateMachine Options:

id (string, required): Unique identifier for the state machine within the .lottie file.
data (object, required): The State Machine JSON object compliant with the spec.
name (string, optional): Human-readable name.

2. Retrieving State Machines

Access added or loaded state machines.

Accessing all state machines: `dotlottie.stateMachines`

Returns an array of LottieStateMachine objects. See dotlottie.stateMachines.

const allStateMachines = dotlottie.stateMachines;
console.log(`Found ${allStateMachines.length} state machines.`);

allStateMachines.forEach((sm) => {
  console.log(`State Machine ID: ${sm.id}, Name: ${sm.name}`);
  // Access the raw data directly
  console.log(" SM Data:", sm.data);
});

Getting a specific state machine: `dotlottie.getStateMachine(stateMachineId)`

Retrieves a LottieStateMachine instance by its id. See dotlottie.getStateMachine().

const toggleSM = dotlottie.getStateMachine("sm_toggle_main");
if (toggleSM) {
  console.log(`Retrieved State Machine: ${toggleSM.name}`);
  console.log(" SM Data:", toggleSM.data);
}

3. Associating State Machines with Animations

State machines control animations by referencing their animationId within the state machine JSON (data).

Implicit Association: The link is defined inside the state machine data you provide to addStateMachine.

// Add animation and then state machines
await dotlottie
  .addAnimation({
    id: "anim_toggle",
    data: toggleAnimationData,
  })
  .addStateMachine({
    id: "starRating",
    name: "Star Rating ⭐",
    data: {
      initial: "global",
      states: [
        {
          name: "global",
          type: "GlobalState",
          transitions: [
            {
              type: "Transition",
              toState: "star_1",
              guards: [
                {
                  type: "Numeric",
                  conditionType: "Equal",
                  inputName: "rating",
                  compareTo: 1,
                },
              ],
            },
            {
              type: "Transition",
              toState: "star_2",
              guards: [
                {
                  type: "Numeric",
                  conditionType: "Equal",
                  inputName: "rating",
                  compareTo: 2,
                },
              ],
            },
            {
              type: "Transition",
              toState: "star_3",
              guards: [
                {
                  type: "Numeric",
                  conditionType: "Equal",
                  inputName: "rating",
                  compareTo: 3,
                },
              ],
            },
            {
              type: "Transition",
              toState: "star_4",
              guards: [
                {
                  type: "Numeric",
                  conditionType: "Equal",
                  inputName: "rating",
                  compareTo: 4,
                },
              ],
            },
            {
              type: "Transition",
              toState: "star_5",
              guards: [
                {
                  type: "Numeric",
                  conditionType: "Equal",
                  inputName: "rating",
                  compareTo: 5,
                },
              ],
            },
          ],
        },
        {
          type: "PlaybackState",
          name: "star_1",
          animation: "",
          autoplay: true,
          segment: "star_1",
          transitions: [],
        },
        {
          type: "PlaybackState",
          name: "star_2",
          animation: "",
          autoplay: true,
          segment: "star_2",
          transitions: [],
        },
        {
          type: "PlaybackState",
          name: "star_3",
          animation: "",
          autoplay: true,
          segment: "star_3",
          transitions: [],
        },
        {
          type: "PlaybackState",
          name: "star_4",
          animation: "",
          autoplay: true,
          segment: "star_4",
          transitions: [],
        },
        {
          type: "PlaybackState",
          name: "star_5",
          animation: "",
          autoplay: true,
          segment: "star_5",
          transitions: [],
        },
      ],
      interactions: [
        {
          type: "PointerDown",
          layerName: "star1",
          actions: [
            {
              type: "SetNumeric",
              inputName: "rating",
              value: 1,
            },
            {
              type: "SetTheme",
              value: "air",
            },
            {
              type: "FireCustomEvent",
              value: "CustomEvent!",
            },
            {
              type: "OpenUrl",
              url: "https://www.lottiefiles.com",
              target: "_blank",
            },
          ],
        },
        {
          type: "PointerDown",
          layerName: "star2",
          actions: [
            {
              type: "SetNumeric",
              inputName: "rating",
              value: 2,
            },
          ],
        },
        {
          type: "PointerDown",
          layerName: "star3",
          actions: [
            {
              type: "SetNumeric",
              inputName: "rating",
              value: 3,
            },
          ],
        },
        {
          type: "PointerDown",
          layerName: "star4",
          actions: [
            {
              type: "SetNumeric",
              inputName: "rating",
              value: 4,
            },
          ],
        },
        {
          type: "PointerDown",
          layerName: "star5",
          actions: [
            {
              type: "SetNumeric",
              inputName: "rating",
              value: 5,
            },
          ],
        },
      ],
      inputs: [
        {
          type: "Numeric",
          name: "rating",
          value: 0,
        },
      ],
    },
  })
  .build();

4. Removing State Machines: `dotlottie.removeStateMachine(stateMachineId)`

Remove a state machine by its id. Returns the DotLottie instance for method chaining. See dotlottie.removeStateMachine().

// Check initial count
const initialSmCount = dotlottie.stateMachines.length;

dotlottie.removeStateMachine("sm_toggle_main");

// Check if count decreased
if (dotlottie.stateMachines.length < initialSmCount) {
  console.log("State Machine 'sm_toggle_main' removed.");
} else {
  console.log("State Machine 'sm_toggle_main' not found or not removed.");
}

// Remember to build!
// await dotlottie.build();

State machines are a powerful V2 feature for creating interactive Lottie experiences. dotlottie-js packages the logic; the player executes it.

Next up: Merging DotLottie Instances