Input and restored snapshots
Start Vue actors with input or a persisted snapshot.
XState v6 is in beta
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();