---
title: useSnapshot
description: Hook to subscribe to a State container's current value
---

import UtilReference from "@/components/docs/api-reference/UtilReference.astro";
import DocsLink from "@/components/docs/DocsLink.astro";

`useSnapshot` subscribes to a `State` container and returns its current value, re-rendering when the value changes. It has two overloads:

**Full state** -- returns the entire state object.

```tsx
function Display({ state }) {
  const value = useSnapshot(state);
  return <span>{value.count}</span>;
}
```

**With selector** -- returns a derived value from the state, re-rendering only when the selected value changes. Pass a custom comparator as the third argument when needed.

```tsx
function Count({ state }) {
  const count = useSnapshot(state, (s) => s.count);
  return <span>{count}</span>;
}
```

### State containers vs stores

A `State` container is a reactive primitive that holds an object value and notifies subscribers on change. Stores are built on top of `State` containers but add features, actions, and lifecycle.

| Hook                                                       | Input          | Subscribes to                    |
| ---------------------------------------------------------- | -------------- | -------------------------------- |
| `useSnapshot`                                              | `State<T>`     | Raw state container              |
| <DocsLink slug="reference/use-store">`useStore`</DocsLink> | Store instance | Store-backed state with features |

Use `useSnapshot` when working with standalone `State` containers outside the player store system -- for example, custom state in component libraries. For player state, use <DocsLink slug="reference/use-player">`usePlayer`</DocsLink> or <DocsLink slug="reference/use-store">`useStore`</DocsLink>.

`useSnapshot` is built on <DocsLink slug="reference/use-selector">`useSelector`</DocsLink> and uses `shallowEqual` by default. The HTML equivalent is `SnapshotController`.

<UtilReference util="useSnapshot" />
