---
title: useSelector
description: Low-level hook for subscribing to derived state with customizable equality checks
---

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

`useSelector` is a low-level hook that subscribes to an external store using React's `useSyncExternalStore`. It accepts a `subscribe` function, a `getSnapshot` function, a `selector` to derive state, and an optional `isEqual` comparator (defaults to `shallowEqual`).

```tsx title="TimeDisplay.tsx"
import { useSelector, shallowEqual } from "@videojs/store/react";

function TimeDisplay({ store }) {
  const time = useSelector(
    (cb) => store.subscribe(cb),
    () => store.state,
    (state) => ({ current: state.currentTime, duration: state.duration }),
    shallowEqual,
  );

  return (
    <span>
      {time.current} / {time.duration}
    </span>
  );
}
```

### Relationship to useStore and useSnapshot

Both `useStore` and `useSnapshot` are built on `useSelector`:

| Hook                                                             | Input                     | Use case                                |
| ---------------------------------------------------------------- | ------------------------- | --------------------------------------- |
| <DocsLink slug="reference/use-store">`useStore`</DocsLink>       | Store instance            | Player and store access with selector   |
| <DocsLink slug="reference/use-snapshot">`useSnapshot`</DocsLink> | `State` container         | Subscribe to raw state changes          |
| `useSelector`                                                    | Custom subscribe/snapshot | Full control over subscription plumbing |

Prefer <DocsLink slug="reference/use-store">`useStore`</DocsLink> for store-backed state and <DocsLink slug="reference/use-snapshot">`useSnapshot`</DocsLink> for `State` containers. Use `useSelector` when you need to integrate with a non-standard external source or customize the equality comparison.

### Equality comparison

The `isEqual` parameter controls when React re-renders. The default `shallowEqual` compares object properties one level deep -- sufficient for most selector return values. Pass a custom comparator for deeply nested objects or when you need reference equality (`Object.is`).

<UtilReference util="useSelector" />
