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

# @xstate/store-react (/docs/xstate-store/react)
The `@xstate/store-react` package provides React bindings for [XState Store](/docs/xstate-store). It includes hooks for subscribing to store state and creating local component stores.

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

## Installation

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

  <Tab value="pnpm" label="pnpm">
    ```bash
    pnpm install @xstate/store-react
    ```
  </Tab>

  <Tab value="yarn" label="yarn">
    ```bash
    yarn add @xstate/store-react
    ```
  </Tab>
</Tabs>

## Quick start

```tsx
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.

```tsx
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`.

```tsx
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.

```tsx
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.

```tsx
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](/docs/xstate-store).