Stately
XstateV6XState Vue

Input and restored snapshots

Start Vue actors with input or a persisted snapshot.

XState v6 is in beta

APIs and behavior may change before the stable release. Read the stable v5 docs.

Pass input as an actor option for a new actor. To resume a persisted actor, create it with restoreActor(...) from xstate/persist, then pass that actor to useActor(...), useMachine(...) or useActorRef(...).

const { snapshot, send } = useActor(checkoutMachine, { input: { cartId } });

const restored = restoreActor(checkoutMachine, persistedSnapshot);
const resumed = useActor(restored);

input creates a fresh initial state from data the actor needs when it starts. restoreActor resumes an actor that already ran. Create the actor once per component instance.

Input from props

<script setup lang="ts">
const props = defineProps<{ cartId: string }>();

const { snapshot, send } = useActor(checkoutMachine, {
  input: { cartId: props.cartId }
});
</script>

Changing cartId later does not restart the actor, because the option was already consumed. Choose one of:

  • send an event, such as send({ type: 'cart.changed', cartId }), and model the change in the machine
  • give the component a :key="cartId" so Vue unmounts the old actor and mounts a new one

Machines that declare required input make the options argument mandatory in TypeScript.

Persisting a snapshot

actorRef.getPersistedSnapshot() returns a serializable value, including persisted children. Save it as the actor changes.

<script setup lang="ts">
import { onBeforeUnmount } from 'vue';
import { useActor } from '@xstate/vue';
import { createActor } from 'xstate';
import { restoreActor } from 'xstate/persist';

const persisted = loadSnapshot();
const restored = persisted
  ? restoreActor(uploadMachine, persisted)
  : undefined;
const actor = restored?.getSnapshot().status === 'error' || !restored
  ? createActor(uploadMachine)
  : restored;
const { snapshot, send, actorRef } = useActor(actor);

const subscription = actorRef.subscribe(() => {
  localStorage.setItem(
    'upload',
    JSON.stringify(actorRef.getPersistedSnapshot())
  );
});

onBeforeUnmount(() => subscription.unsubscribe());
</script>

Read it back before the actor is created:

function loadSnapshot() {
  const raw = localStorage.getItem('upload');
  if (!raw) return undefined;
  try {
    return JSON.parse(raw);
  } catch {
    return undefined;
  }
}

Stored snapshots are untrusted input. loadSnapshot() rejects invalid JSON; the actor setup above also falls back to a fresh actor when restoration reports an incompatible snapshot. See Persist and restore actors for versioning.

Keep machine definitions out of Vue's deep ref(...) and reactive(...) wrappers. Store a machine in shallowRef(machine) or call markRaw(machine) before putting it in reactive state. This keeps the machine's state nodes raw when creating or restoring actors:

import { shallowRef } from 'vue';
import { createActor } from 'xstate';
import { restoreActor } from 'xstate/persist';

const machineRef = shallowRef(uploadMachine);
const actor = persisted
  ? restoreActor(machineRef.value, persisted)
  : createActor(machineRef.value);
const { snapshot, send } = useActor(actor);

What restoring does

A restored actor starts in the persisted state. Actions that already ran are not re-executed. Invoked actors are restarted and spawned actors are restored recursively, so a machine restored inside uploading starts the upload request again.

Warning: Do not persist a snapshot that holds values which cannot survive JSON.stringify: DOM nodes, file handles, promises. Keep those out of context, or model them as invoked actors that are recreated on restore.

Cheatsheet

useActor(logic, { input });
useActor(restoreActor(logic, persisted));
useActorRef(restoreActor(logic, persisted));

actorRef.getPersistedSnapshot();

On this page