@xstate/store-react

The @xstate/store-react package provides React bindings for XState Store. It includes hooks for subscribing to store state and creating local component stores.

This package re-exports all of @xstate/store, so you only need to install @xstate/store-react.

Installation

npm install @xstate/store-react

pnpm install @xstate/store-react

yarn add @xstate/store-react

Quick start

import { createStore, useSelector } from '@xstate/store-react';

const store = createStore({
  context: { count: 0 },
  on: {
    inc: (context, event: { by?: number }) => ({
      count: context.count + (event.by ?? 1),
    }),
  },
});

function Counter() {
  const count = useSelector(store, (state) => state.context.count);

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => store.trigger.inc()}>+1</button>
      <button onClick={() => store.trigger.inc({ by: 5 })}>+5</button>
    </div>
  );
}

API

`useSelector(store, selector?, compare?)`

Subscribes to a store and returns a selected value. The component re-renders when the selected value changes.

import { useSelector } from '@xstate/store-react';

function Counter() {
  // Select specific value
  const count = useSelector(store, (state) => state.context.count);

  // With custom comparison function
  const user = useSelector(
    store,
    (state) => state.context.user,
    (prev, next) => prev.id === next.id
  );

  return <div>Count: {count}</div>;
}

Parameters:

store - The store to subscribe to
selector - Optional function to select a value from the store snapshot
compare - Optional comparison function (defaults to strict equality ===)

Returns: The selected value

`useStore(config)`

Creates a component-scoped store instance. Useful for local state management similar to useReducer.

import { useStore, useSelector } from '@xstate/store-react';

function Counter({ initialCount = 0 }) {
  const store = useStore({
    context: { count: initialCount },
    on: {
      inc: (context) => ({ count: context.count + 1 }),
      dec: (context) => ({ count: context.count - 1 }),
    },
  });

  const count = useSelector(store, (state) => state.context.count);

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => store.trigger.inc()}>+</button>
      <button onClick={() => store.trigger.dec()}>-</button>
    </div>
  );
}

Parameters:

config - Store configuration object (same as createStore)

Returns: A store instance (stable across re-renders)

`useAtom(atom, selector?, compare?)`

Subscribes to an atom and returns its value. Since v3.7.0.

import { createAtom } from '@xstate/store-react';
import { useAtom } from '@xstate/store-react';

const countAtom = createAtom(0);

function Counter() {
  const count = useAtom(countAtom);

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => countAtom.set((prev) => prev + 1)}>+</button>
    </div>
  );
}

Parameters:

atom - The atom to subscribe to
selector - Optional function to select a value from the atom
compare - Optional comparison function

Returns: The (selected) atom value

`createStoreHook(config)`

Creates a custom React hook that combines useStore() and useSelector(). Since v3.9.0.

import { createStoreHook } from '@xstate/store-react';

const useCountStore = createStoreHook({
  context: { count: 0 },
  on: {
    inc: (ctx, event: { by: number }) => ({
      count: ctx.count + event.by,
    }),
  },
});

function Counter() {
  const [count, store] = useCountStore((s) => s.context.count);

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => store.trigger.inc({ by: 1 })}>+1</button>
      <button onClick={() => store.trigger.inc({ by: 5 })}>+5</button>
    </div>
  );
}

Parameters:

config - Store configuration object

Returns: A custom hook that returns [selectedValue, store]

Full documentation

For complete XState Store documentation including context, transitions, effects, atoms, and more, see the XState Store docs.

@xstate/store-react

On this page