Skip to main content

​
Reference

​
useStore

function useStore<TAtom extends AnyAtom | undefined, T>(
  atom: TAtom,
  selector: (
    snapshot: TAtom extends { get: () => infer TSnapshot }
      ? TSnapshot
      : undefined,
  ) => T,
  compare?: (a: T, b: T) => boolean
): T
A React hook that subscribes to a TanStack Store atom and returns the selected state. The component will re-render when the selected state changes according to the comparison function.
​
atom
AnyAtom | undefined
The store atom to subscribe to. Can be undefined to support conditional usage.
​
selector
(snapshot: TSnapshot) => T
A function that selects a slice of state from the atom’s snapshot. Use this to optimize re-renders by selecting only the data your component needs.
​
compare
(a: T, b: T) => boolean
default:"Object.is"
Optional comparison function to determine if the selected state has changed. Defaults to reference equality (Object.is). Use shallow for shallow object comparison.

​
Returns

​
T
T
The selected state value from the atom.

​
Usage

​
Basic Usage

import { useStore } from '@tanstack/react-store'
import { store } from './store'

function Counter() {
  const count = useStore(store, (state) => state.count)

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

​
With Custom Comparison

import { useStore, shallow } from '@tanstack/react-store'
import { store } from './store'

function UserProfile() {
  // Only re-render if user object properties change (shallow comparison)
  const user = useStore(
    store,
    (state) => ({ name: state.name, email: state.email }),
    shallow
  )

  return (
    <div>
      <p>{user.name}</p>
      <p>{user.email}</p>
    </div>
  )
}

​
Selecting Multiple Values

import { useStore } from '@tanstack/react-store'
import { store } from './store'

function Dashboard() {
  const stats = useStore(store, (state) => ({
    total: state.items.length,
    completed: state.items.filter(i => i.done).length
  }))

  return (
    <div>
      <p>Total: {stats.total}</p>
      <p>Completed: {stats.completed}</p>
    </div>
  )
}

​
Notes

  • Built on top of React’s useSyncExternalStoreWithSelector for optimal concurrent rendering support
  • Automatically handles subscription cleanup when the component unmounts
  • The selector function should be stable or memoized to avoid unnecessary re-subscriptions
  • Supports undefined atoms for conditional store usage
  • Uses reference equality by default - provide a custom compare function for object comparisons