xstate-vue2

Vue 2 composables for xstate and @xstate/fsm

• Quick Start
• API
  • useMachine(machine, options?)
  • useService(service)
  • useActor(actor, getSnapshot)
  • useInterpret(machine, options?, observer?)
  • useSelector(actor, selector, compare?, getSnapshot?)
  • useMachine(machine) with @xstate/fsm
• Configuring Machines
• Matching States
• Persisted and Rehydrated State

Quick Start

1. Install xstate (or @xstate/fsm) andxstate-vue2

1npm i xstate xstate-vue2

2. Import the useMachine composition function:

1<template>
2  <button @click="send('TOGGLE')">
3    {{
4      state.value === 'inactive'
5        ? 'Click to activate'
6        : 'Active! Click to deactivate'
7    }}
8  </button>
9</template>
10
11<script>
12import { useMachine } from 'xstate-vue2';
13import { createMachine } from 'xstate';
14
15const toggleMachine = createMachine({
16  id: 'toggle',
17  initial: 'inactive',
18  states: {
19    inactive: {
20      on: { TOGGLE: 'active' }
21    },
22    active: {
23      on: { TOGGLE: 'inactive' }
24    }
25  }
26});
27
28export default {
29  setup() {
30    const { state, send } = useMachine(toggleMachine);
31    return {
32      state,
33      send
34    };
35  }
36};
37</script>

API

useMachine(machine, options?)

A Vue composition function that interprets the given machine and starts a service that runs for the lifetime of the component.

Arguments

• machine - An XState machine.
• options (optional) - Interpreter options OR one of the following Machine Config options: guards, actions, activities, services, delays, immediate, context, or state.

Returns { state, send, service}:

• state - Represents the current state of the machine as an XState State object.
• send - A function that sends events to the running service.
• service - The created service.

useService(service)

A Vue composition function that subscribes to state changes from an existing service.

Arguments

• service - An XState service.

Returns {state, send}:

• state - Represents the current state of the service as an XState State object.
• send - A function that sends events to the running service.

useActor(actor, getSnapshot)

A Vue composition function that subscribes to emitted changes from an existing actor.

Since 0.5.0

Arguments

• actor - an actor-like object that contains .send(...) and .subscribe(...) methods.
• getSnapshot - a function that should return the latest emitted value from the actor.
  • Defaults to attempting to get the actor.state, or returning undefined if that does not exist.

1import { useActor } from 'xstate-vue2';
2
3export default {
4  props: ['someSpawnedActor'],
5  setup(props) {
6    const { state, send } = useActor(props.someSpawnedActor);
7    return { state, send };
8  }
9};

useInterpret(machine, options?, observer?)

A Vue composition function that returns the service created from the machine with the options, if specified. It also sets up a subscription to the service with the observer, if provided.

Since 0.5.0

Arguments

• machine - An XState machine or a function that lazily returns a machine.
• options (optional) - Interpreter options and/or any of the following machine config options: guards, actions, services, delays, immediate, context, state.
• observer (optional) - an observer or listener that listens to state updates:
  • an observer (e.g., { next: (state) => {/* ... */} })
  • or a listener (e.g., (state) => {/* ... */})

1import { useInterpret } from 'xstate-vue2';
2import { someMachine } from '../path/to/someMachine';
3export default {
4  setup() {
5    const service = useInterpret(someMachine);
6    return service;
7  }
8};

With options + listener:

1import { useInterpret } from 'xstate-vue2';
2import { someMachine } from '../path/to/someMachine';
3export default {
4  setup() {
5    const service = useInterpret(
6      someMachine,
7      {
8        actions: {
9          /* ... */
10        }
11      },
12      (state) => {
13        // subscribes to state changes
14        console.log(state.value);
15      }
16    );
17    // ...
18  }
19};

useSelector(actor, selector, compare?, getSnapshot?)

A Vue composition function that returns the selected value from the snapshot of an actor, such as a service. This hook will only cause a rerender if the selected value changes, as determined by the optional compare function.

Since 0.6.0

Arguments

• actor - a service or an actor-like object that contains .send(...) and .subscribe(...) methods.
• selector - a function that takes in an actor's "current state" (snapshot) as an argument and returns the desired selected value.
• compare (optional) - a function that determines if the current selected value is the same as the previous selected value.
• getSnapshot (optional) - a function that should return the latest emitted value from the actor.
  • Defaults to attempting to get the actor.state, or returning undefined if that does not exist. Will automatically pull the state from services.

1import { useSelector } from '@xstate/vue';
2const selectCount = (state) => state.context.count;
3export default {
4  props: ['service'],
5  setup(props) {
6    const count = useSelector(props.service, selectCount);
7    // ...
8    return { count };
9  }
10};

With compare function:

1import { useSelector } from '@xstate/vue';
2const selectUser = (state) => state.context.user;
3const compareUser = (prevUser, nextUser) => prevUser.id === nextUser.id;
4export default {
5  props: ['service'],
6  setup(props) {
7    const user = useSelector(props.service, selectUser, compareUser);
8    // ...
9    return { user };
10  }
11};

With useInterpret(...):

1import { useInterpret, useSelector } from '@xstate/vue';
2import { someMachine } from '../path/to/someMachine';
3const selectCount = (state) => state.context.count;
4export default {
5  setup() {
6    const service = useInterpret(someMachine);
7    const count = useSelector(service, selectCount);
8    // ...
9    return { count, service };
10  }
11};

useMachine(machine) with @xstate/fsm

A Vue composition function that interprets the given finite state machine from [@xstate/fsm] and starts a service that runs for the lifetime of the component.

Arguments

• machine - An XState finite state machine (FSM).

Returns an object {state, send, service}:

• state - Represents the current state of the machine as an @xstate/fsm StateMachine.State object.
• send - A function that sends events to the running service.
• service - The created @xstate/fsm service.

Example (TODO)

Configuring Machines

Existing machines can be configured by passing the machine options as the 2nd argument of useMachine(machine, options).

Example: the 'fetchData' service and 'notifySuccess' action are both configurable:

1<template>
2  <template v-if="state.value === 'idle'">
3    <button @click="send('FETCH', { query: 'something' })">
4      Search for something
5    </button>
6  </template>
7
8  <template v-else-if="state.value === 'loading'">
9    <div>Searching...</div>
10  </template>
11
12  <template v-else-if="state.value === 'success'">
13    <div>Success! {{ state.context.data }}</div>
14  </template>
15
16  <template v-else-if="state.value === 'failure'">
17    <p>{{ state.context.error.message }}</p>
18    <button @click="send('RETRY')">Retry</button>
19  </template>
20</template>
21
22<script>
23import { assign, Machine } from 'xstate';
24import { useMachine } from 'xstate-vue2';
25
26const fetchMachine = createMachine({
27  id: 'fetch',
28  initial: 'idle',
29  context: {
30    data: undefined,
31    error: undefined
32  },
33  states: {
34    idle: {
35      on: { FETCH: 'loading' }
36    },
37    loading: {
38      invoke: {
39        src: 'fetchData',
40        onDone: {
41          target: 'success',
42          actions: assign({
43            data: (_context, event) => event.data
44          })
45        },
46        onError: {
47          target: 'failure',
48          actions: assign({
49            error: (_context, event) => event.data
50          })
51        }
52      }
53    },
54    success: {
55      entry: 'notifySuccess',
56      type: 'final'
57    },
58    failure: {
59      on: {
60        RETRY: 'loading'
61      }
62    }
63  }
64});
65
66export default {
67  props: {
68    onResolve: {
69      type: Function,
70      default: () => {}
71    }
72  },
73  setup(props) {
74    const { state, send } = useMachine(fetchMachine, {
75      actions: {
76        notifySuccess: (ctx) => props.onResolve(ctx.data)
77      },
78      services: {
79        fetchData: (_context, event) =>
80          fetch(`some/api/${event.query}`).then((res) => res.json())
81      }
82    });
83    return {
84      state,
85      send
86    };
87  }
88};
89</script>

Matching States

For hierarchical and parallel machines, the state values will be objects, not strings. In this case, it's better to use state.matches(...):

1<template>
2  <div>
3    <loader-idle v-if="state.matches('idle')" />
4    <loader-loading-user v-if-else="state.matches({ loading: 'user' })" />
5    <loader-loading-friends v-if-else="state.matches({ loading: 'friends' })" />
6  </div>
7</template>

Persisted and Rehydrated State

You can persist and rehydrate state with useMachine(...) via options.state:

1<script>
2// Get the persisted state config object from somewhere, e.g. localStorage
3const persistedState = JSON.parse(
4  localStorage.getItem('some-persisted-state-key')
5);
6
7export default {
8  setup() {
9    const { state, send } = useMachine(someMachine, {
10      state: persistedState
11    });
12
13    // state will initially be that persisted state, not the machine's initialState
14    return { state, send };
15  }
16};
17</script>