# @xstate/vue
# Quick Start
- Install
xstate
and@xstate/vue
:
npm i xstate @xstate/vue
Via CDN
<script src="https://unpkg.com/@xstate/vue/dist/xstate-vue.min.js"></script>
By using the global variable XStateVue
or
<script src="https://unpkg.com/@xstate/vue/dist/xstate-vue.fsm.min.js"></script>
By using the global variable XStateVueFSM
- Import the
useMachine
composition function:
<template>
<button @click="send('TOGGLE')">
{{
state.value === 'inactive'
? 'Click to activate'
: 'Active! Click to deactivate'
}}
</button>
</template>
<script>
import { useMachine } from '@xstate/vue';
import { Machine } from 'xstate';
const toggleMachine = Machine({
id: 'toggle',
initial: 'inactive',
states: {
inactive: {
on: { TOGGLE: 'active' }
},
active: {
on: { TOGGLE: 'inactive' }
}
}
});
export default {
setup() {
const { state, send } = useMachine(toggleMachine);
return {
state,
send
};
}
};
</script>
Vue 2.x notice: If you're using Vue 2.x, please see the recipe (opens new window) instead.
# API
# useMachine(machine, options?)
A Vue composition function (opens new window) that interprets the given machine
and starts a service that runs for the lifetime of the component.
Arguments
machine
- An XState machine (opens new window).options
(optional) - Interpreter options (opens new window) OR one of the following Machine Config options:guards
,actions
,activities
,services
,delays
,immediate
,context
, orstate
.
Returns { state, send, service}
:
state
- Represents the current state of the machine as an XStateState
object.send
- A function that sends events to the running service.service
- The created service.
# useService(service)
A Vue composition function (opens new window) that subscribes to state changes from an existing service.
Arguments
service
- An XState service (opens new window).
Returns {state, send}
:
state
- Represents the current state of the service as an XStateState
object.send
- A function that sends events to the running service.
# useMachine(machine)
with @xstate/fsm
A Vue composition function (opens new window) that interprets the given finite state machine
from [@xstate/fsm
] and starts a service that runs for the lifetime of the component.
This special useMachine
hook is imported from @xstate/vue/lib/fsm
Arguments
machine
- An XState finite state machine (FSM) (opens new window).
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 (TODO)
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:
Example (TODO)
# Matching States
For hierarchical (opens new window) and parallel (opens new window) machines, the state values will be objects, not strings. In this case, it's better to use state.matches(...)
(opens new window):
<template>
<div>
<loader-idle v-if="state.matches('idle')" />
<loader-loading-user v-if-else="state.matches({ loading: 'user' })" />
<loader-loading-friends v-if-else="state.matches({ loading: 'friends' })" />
</div>
</template>
# Persisted and Rehydrated State
You can persist and rehydrate state with useMachine(...)
via options.state
:
<script>
// Get the persisted state config object from somewhere, e.g. localStorage
const persistedState = JSON.parse(
localStorage.getItem('some-persisted-state-key')
);
export default {
setup() {
const { state, send } = useMachine(someMachine, {
state: persistedState
});
// state will initially be that persisted state, not the machine's initialState
return { state, send };
}
};
</script>