# Source: https://stately.ai/docs/xstate-svelte.mdx

# @xstate/svelte (/docs/xstate-svelte)
The [@xstate/svelte package](https://github.com/statelyai/xstate/tree/main/packages/xstate-svelte) contains utilities for using [XState](https://github.com/statelyai/xstate) with [Svelte](https://github.com/sveltejs/svelte).

## Templates

Use the following templates to get started quickly with XState and Svelte:

* [XState Svelte template (CodeSandbox)](https://codesandbox.io/p/devbox/github/statelyai/xstate/tree/main/templates/svelte-ts)
* [XState Svelte template (StackBlitz)](https://stackblitz.com/github/statelyai/xstate/tree/main/templates/svelte-ts?file=%2Fsrc%2FfeedbackMachine.ts)

## Installation

Install the latest versions of both `xstate` and `@xstate/svelte`. `xstate` is a peer dependency of `@xstate/svelte`.

<Tabs items={['npm', 'pnpm', 'yarn']}>
  <Tab value="npm" label="npm">
    ```bash
    npm install xstate @xstate/svelte
    ```
  </Tab>

  <Tab value="pnpm" label="pnpm">
    ```bash
    pnpm install xstate @xstate/svelte
    ```
  </Tab>

  <Tab value="yarn" label="yarn">
    ```bash
    yarn add xstate @xstate/svelte
    ```
  </Tab>
</Tabs>

## API

### `useMachine(machine, options?)`

A function that creates an actor from the given `machine` and starts an actor that runs for the lifetime of the component.

**Arguments**

* `machine` - An [XState machine](machines).
* `options` (optional) - Actor options

**Returns** `{ snapshot, send, actorRef}`:

* `snapshot` - A [Svelte store](https://svelte.dev/docs#svelte_store) representing the current state of the machine
* `send` - A function that sends events to the running actor ref.
* `actorRef` - The created actor ref.

### `useSelector(actorRef, selector, compare?, getSnapshot?)`

A function that returns [Svelte store](https://svelte.dev/docs#svelte_store) representing the selected value from the snapshot of an `actorRef`, such as an actor. The store will only be updated when the selected value changes, as determined by the optional `compare` function.

**Arguments**

* `actorRef` - An actor ref
* `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.

#### Examples

*Coming soon*

## Matching States

When using [hierarchical](https://xstate.js.org/docs/guides/hierarchical.html) and [parallel](https://xstate.js.org/docs/guides/parallel.html) machines, the state values will be objects, not strings. In this case, it is best to use [`state.matches(...)`](https://xstate.js.org/docs/guides/states.html#state-methods-and-properties).

```svelte
{#if $state.matches('idle')}
  //
{:else if $state.matches({ loading: 'user' })}
  //
{:else if $state.matches({ loading: 'friends' })}
  //
{/if}
```

## Persisted and Rehydrated State

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

```js
// Get the persisted state config object from somewhere, e.g. localStorage
// [!code highlight:3]
const persistedState = JSON.parse(
  localStorage.getItem('some-persisted-state-key'),
);

const { snapshot, send } = useMachine(someMachine, {
  // [!code highlight:1]
  snapshot: persistedState,
});

// state will initially be that persisted state, not the machineâs initialState
```