Zustand

https://github.com/pmndrs/zustand
Admin
Zustand is a small, fast, and scalable state-management solution for React applications, offering a...
Tokens:136,840
Snippets:863
Trust Score:9.6
License:MIT
Update:3 days ago
Show doc for...
Tokens:
Raw
### Set up locally with git clone and pnpm

Source: https://github.com/pmndrs/zustand/blob/main/examples/starter/README.md

Clone the Zustand repository, install dependencies, build the library, move to the examples/starter folder, install its dependencies, and start the dev server.

```bash
git clone https://github.com/pmndrs/zustand

# install project dependencies & build the library
cd zustand && pnpm install

# move to the examples folder & install dependencies
cd examples/starter && pnpm install

# start the dev server
pnpm dev
```

--------------------------------

### Install zustand with npm

Source: https://github.com/pmndrs/zustand/blob/main/README.md

Install the zustand package using npm. This is the first step to using the library.

```bash
npm install zustand
```

--------------------------------

### Complete example of persist with manual hydration

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/middlewares/persist.md

Complete example combining store creation, pointer tracking, rendering, and delayed manual rehydration.

```ts
import { createStore } from 'zustand/vanilla'
import { persist } from 'zustand/middleware'

type PositionStoreState = { position: { x: number; y: number } }

type PositionStoreActions = {
  setPosition: (nextPosition: PositionStoreState['position']) => void
}

type PositionStore = PositionStoreState & PositionStoreActions

const positionStore = createStore<PositionStore>()(
  persist(
    (set) => ({
      position: { x: 0, y: 0 },
      setPosition: (position) => set({ position }),
    }),
    {
      name: 'position-storage',
      skipHydration: true,
    },
  ),
)

const $dotContainer = document.getElementById('dot-container') as HTMLDivElement
const $dot = document.getElementById('dot') as HTMLDivElement

$dotContainer.addEventListener('pointermove', (event) => {
  positionStore.getState().setPosition({
    x: event.clientX,
    y: event.clientY,
  })
})

const render: Parameters<typeof positionStore.subscribe>[0] = (state) => {
  $dot.style.transform = `translate(${state.position.x}px, ${state.position.y}px)`
}

setTimeout(() => {
  positionStore.persist.rehydrate()
}, 2000)

render(positionStore.getState(), positionStore.getState())

positionStore.subscribe(render)
```

--------------------------------

### Install Zustand with npm

Source: https://github.com/pmndrs/zustand/blob/main/docs/learn/getting-started/introduction.md

Install the Zustand package from NPM. Use any package manager of your choice.

```bash
# NPM
npm install zustand
# Or, use any package manager of your choice.
```

--------------------------------

### Complete example with provider and hook consumer

Source: https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/initialize-state-with-props.md

Complete example showing the provider wrapper and custom hook consumer together. The provider passes initial props (bears: 2) and the consumer uses the custom hook.

```tsx
function App2() {
  return (
    <BearProvider bears={2}>
      <HookConsumer />
    </BearProvider>
  )
}
```

--------------------------------

### Vitest setup with zustand mock (setup-vitest.ts)

Source: https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/testing.md

Vitest setup file that imports jest-dom matchers and mocks the zustand module. Requires adding `import { vi } from 'vitest'` if globals configuration is not enabled.

```ts
// setup-vitest.ts
import '@testing-library/jest-dom/vitest'

vi.mock('zustand') // to make it work like Jest (auto-mocking)
```

--------------------------------

### Install Immer

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/integrations/immer-middleware.md

Install Immer as a direct dependency to use the Immer middleware with Zustand.

```bash
npm install immer
```

--------------------------------

### Complete code for persisting position tracker

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/middlewares/persist.md

Full example combining store setup, event listener, and rendering, with the persist middleware for localStorage persistence.

```TypeScript
import { createStore } from 'zustand/vanilla'
import { persist } from 'zustand/middleware'

type PositionStoreState = { position: { x: number; y: number } }

type PositionStoreActions = {
  setPosition: (nextPosition: PositionStoreState['position']) => void
}

type PositionStore = PositionStoreState & PositionStoreActions

const positionStore = createStore<PositionStore>()(
  persist(
    (set) => ({
      position: { x: 0, y: 0 },
      setPosition: (position) => set({ position }),
    }),
    { name: 'position-storage' },
  ),
)

const $dotContainer = document.getElementById('dot-container') as HTMLDivElement
const $dot = document.getElementById('dot') as HTMLDivElement

$dotContainer.addEventListener('pointermove', (event) => {
  positionStore.getState().setPosition({
    x: event.clientX,
    y: event.clientY,
  })
})

const render: Parameters<typeof positionStore.subscribe>[0] = (state) => {
  $dot.style.transform = `translate(${state.position.x}px, ${state.position.y}px)`
}

render(positionStore.getState(), positionStore.getState())

positionStore.subscribe(render)
```

--------------------------------

### Complete code for global vanilla store example

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/hooks/use-store-with-equality-fn.md

This is the complete code for the global vanilla store example, including the necessary imports from 'zustand/traditional' and 'zustand/shallow'. It shows the full implementation of the MovingDot component and its usage in App.

```tsx
import { createStore } from 'zustand'
import { useStoreWithEqualityFn } from 'zustand/traditional'
import { shallow } from 'zustand/shallow'

type PositionStoreState = { position: { x: number; y: number } }

type PositionStoreActions = {
  setPosition: (nextPosition: PositionStoreState['position']) => void
}

type PositionStore = PositionStoreState & PositionStoreActions

const positionStore = createStore<PositionStore>()((set) => ({
  position: { x: 0, y: 0 },
  setPosition: (position) => set({ position }),
}))

function MovingDot() {
  const position = useStoreWithEqualityFn(
    positionStore,
    (state) => state.position,
    shallow,
  )
  const setPosition = useStoreWithEqualityFn(
    positionStore,
    (state) => state.setPosition,
    shallow,
  )

  return (
    <div
      onPointerMove={(e) => {
        setPosition({
          x: e.clientX,
          y: e.clientY,
        })
      }}
      style={{
        position: 'relative',
        width: '100vw',
        height: '100vh',
      }}
    >
      <div
        style={{
          position: 'absolute',
          backgroundColor: 'red',
          borderRadius: '50%',
          transform: `translate(${position.x}px, ${position.y}px)`,
          left: -10,
          top: -10,
          width: 20,
          height: 20,
        }}
      />
    </div>
  )
}

export default function App() {
  return <MovingDot />
}
```

--------------------------------

### Full example code without useShallow

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/hooks/use-shallow.md

The complete example code combining the store, meals array, UpdateBabyBearMeal, BearNames, and App components. This is the full code shown after the individual steps.

```tsx
import { useEffect } from 'react'
import { create } from 'zustand'

type BearFamilyMealsStore = {
  [key: string]: string
}

const useBearFamilyMealsStore = create<BearFamilyMealsStore>()(() => ({
  papaBear: 'large porridge-pot',
  mamaBear: 'middle-size porridge pot',
  babyBear: 'A little, small, wee pot',
}))

const meals = [
  'A tiny, little, wee bowl',
  'A small, petite, tiny pot',
  'A wee, itty-bitty, small bowl',
  'A little, petite, tiny dish',
  'A tiny, small, wee vessel',
  'A small, little, wee cauldron',
  'A little, tiny, small cup',
  'A wee, small, little jar',
  'A tiny, wee, small pan',
  'A small, wee, little crock',
]

function UpdateBabyBearMeal() {
  useEffect(() => {
    const timer = setInterval(() => {
      useBearFamilyMealsStore.setState({
        babyBear: meals[Math.floor(Math.random() * (meals.length - 1))],
      })
    }, 1000)

    return () => {
      clearInterval(timer)
    }
  }, [])

  return null
}

function BearNames() {
  const names = useBearFamilyMealsStore((state) => Object.keys(state))

  return <div>{names.join(', ')}</div>
}

export default function App() {
  return (
    <>
      <UpdateBabyBearMeal />
      <BearNames />
    </>
  )
}
```

--------------------------------

### combine middleware usage example

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/middlewares/combine.md

Shows the basic syntax of combine, which takes an initial state and an additional state creator function.

```js
const nextStateCreatorFn = combine(initialState, additionalStateCreatorFn)
```

--------------------------------

### Configure Vitest with setup file (vitest.config.ts)

Source: https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/testing.md

Vitest configuration that merges with the existing Vite config, enabling globals, jsdom environment, and the setup file. Adjust the root and __mocks__ directory location if you change the Vitest root.

```ts
// vitest.config.ts
import { defineConfig, mergeConfig } from 'vitest/config'
import viteConfig from './vite.config'

export default defineConfig((configEnv) =>
  mergeConfig(
    viteConfig(configEnv),
    defineConfig({
      test: {
        globals: true,
        environment: 'jsdom',
        setupFiles: ['./setup-vitest.ts'],
      },
    }),
  ),
)
```

--------------------------------

### Jest setup file

Source: https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/testing.md

Jest setup file that imports @testing-library/jest-dom to add custom matchers for DOM assertions.

```ts
// setup-jest.ts
import '@testing-library/jest-dom'
```

--------------------------------

### Complete example: global vanilla store with MovingDot

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/hooks/use-store.md

The full code combining the store definition, MovingDot component, and App component, as shown in the documentation.

```tsx
import { createStore, useStore } from 'zustand'

type PositionStoreState = { position: { x: number; y: number } }

type PositionStoreActions = {
  setPosition: (nextPosition: PositionStoreState['position']) => void
}

type PositionStore = PositionStoreState & PositionStoreActions

const positionStore = createStore<PositionStore>()((set) => ({
  position: { x: 0, y: 0 },
  setPosition: (position) => set({ position }),
}))

function MovingDot() {
  const position = useStore(positionStore, (state) => state.position)
  const setPosition = useStore(positionStore, (state) => state.setPosition)

  return (
    <div
      onPointerMove={(e) => {
        setPosition({
          x: e.clientX,
          y: e.clientY,
        })
      }}
      style={{
        position: 'relative',
        width: '100vw',
        height: '100vh',
      }}
    >
      <div
        style={{
          position: 'absolute',
          backgroundColor: 'red',
          borderRadius: '50%',
          transform: `translate(${position.x}px, ${position.y}px)`,
          left: -10,
          top: -10,
          width: 20,
          height: 20,
        }}
      />
    </div>
  )
}

export default function App() {
  return <MovingDot />
}
```

--------------------------------

### Using useStore with React context for a position store

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/hooks/use-store.md

Shows a complete example of creating a store with createStore, providing it via React context, and consuming it with a custom usePositionStore hook that uses useStore. The example includes a MovingDot component that updates its position on pointer move.

```tsx
import { type ReactNode, useState, createContext, useContext } from 'react'
import { createStore, useStore } from 'zustand'

type PositionStoreState = { position: { x: number; y: number } }

type PositionStoreActions = {
  setPosition: (nextPosition: PositionStoreState['position']) => void
}

type PositionStore = PositionStoreState & PositionStoreActions

const createPositionStore = () => {
  return createStore<PositionStore>()((set) => ({
    position: { x: 0, y: 0 },
    setPosition: (position) => set({ position }),
  }))
}

const PositionStoreContext = createContext<ReturnType<
  typeof createPositionStore
> | null>(null)

function PositionStoreProvider({ children }: { children: ReactNode }) {
  const [store] = useState(() => createPositionStore())
  return (
    <PositionStoreContext.Provider value={store}>
      {children}
    </PositionStoreContext.Provider>
  )
}

function usePositionStore<U>(selector: (state: PositionStore) => U) {
  const store = useContext(PositionStoreContext)

  if (store === null) {
    throw new Error(
      'usePositionStore must be used within PositionStoreProvider',
    )
  }

  return useStore(store, selector)
}

function MovingDot({ color }: { color: string }) {
  const position = usePositionStore((state) => state.position)
  const setPosition = usePositionStore((state) => state.setPosition)

  return (
    <div
      onPointerMove={(e) => {
        setPosition({
          x:
            e.clientX > e.currentTarget.clientWidth
              ? e.clientX - e.currentTarget.clientWidth
              : e.clientX,
          y: e.clientY,
        })
      }}
      style={{
        position: 'relative',
        width: '50vw',
        height: '100vh',
      }}
    >
      <div
        style={{
          position: 'absolute',
          backgroundColor: color,
          borderRadius: '50%',
          transform: `translate(${position.x}px, ${position.y}px)`,
          left: -10,
          top: -10,
          width: 20,
          height: 20,
        }}
      />
    </div>
  )
}

export default function App() {
  return (
    <div style={{ display: 'flex' }}>
      <PositionStoreProvider>
        <MovingDot color="red" />
      </PositionStoreProvider>
      <PositionStoreProvider>
        <MovingDot color="blue" />
      </PositionStoreProvider>
    </div>
  )
}
```

--------------------------------

### immer usage example

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/middlewares/immer.md

Example of using immer middleware to make immutable updates easier in a zustand store.

```js
const nextStateCreatorFn = immer(stateCreatorFn)
```

--------------------------------

### Current store state example

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/integrations/persisting-store-data.md

Example of the current Zustand store state with a nested foo object containing an extra baz field.

```ts
{
  foo: {
    bar: 0,
    baz: 1,
  }
}
```

--------------------------------

### Example vanilla store with BearState

Source: https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/auto-generating-selectors.md

A sample vanilla Zustand store using `createStore` with a `BearState` interface. This store is used with the vanilla `createSelectors` function.

```typescript
import { createStore } from 'zustand'

interface BearState {
  bears: number
  increase: (by: number) => void
  increment: () => void
}

const store = createStore<BearState>()((set) => ({
  bears: 0,
  increase: (by) => set((state) => ({ bears: state.bears + by })),
  increment: () => set((state) => ({ bears: state.bears + 1 })),
}))
```

--------------------------------

### Build and run commands for SSR

Source: https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/ssr-and-hydration.md

Commands to compile the TypeScript project and start the Node server.

```sh
tsc --build
```

```sh
node server.js
```

--------------------------------

### Read from state in actions using get

Source: https://github.com/pmndrs/zustand/blob/main/README.md

Shows how to access state outside of set updates using the get function. The example is truncated in the source, but the pattern is to call get().property.

```jsx
const useSoundStore = create((set, get) => ({
  sound: 'grunt',
  action: () => {
    const sound = get().sound
    ...
```

--------------------------------

### Tutorial steps for versioned persistence with migrate

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/middlewares/persist.md

These are the individual steps of the tutorial: seeding a version 0 state in localStorage, defining the migrate function, tracking pointer moves, and rendering the dot position. They are shown separately before the complete code.

```ts
// For tutorial purposes only
if (!localStorage.getItem('position-storage')) {
  localStorage.setItem(
    'position-storage',
    JSON.stringify({
      state: { x: 100, y: 100 }, // version 0 structure
      version: 0,
    }),
  )
}
```

```ts
migrate: (persisted: any, version) => {
  if (version === 0) {
    persisted.position = { x: persisted.x, y: persisted.y }
    delete persisted.x
    delete persisted.y
  }

  return persisted
}
```

```ts
const $dotContainer = document.getElementById('dot-container') as HTMLDivElement
const $dot = document.getElementById('dot') as HTMLDivElement

$dotContainer.addEventListener('pointermove', (event) => {
  positionStore.getState().setPosition({
    x: event.clientX,
    y: event.clientY,
  })
})
```

```ts
const render: Parameters<typeof positionStore.subscribe>[0] = (state) => {
  $dot.style.transform = `translate(${state.position.x}px, ${state.position.y}px)`
}

render(positionStore.getState(), positionStore.getState())

positionStore.subscribe(render)
```

--------------------------------

### Create a vanilla store with createStore and subscribe to it

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/apis/create-store.md

Example showing how to use createStore from zustand/vanilla to manage a person object and update the DOM on state changes. It demonstrates subscribing to the store with subscribe and rendering the initial state with getInitialState. The highlighted lines (32-34, 38-40, 44-46) correspond to the event handlers that update the store.

```ts
import { createStore } from 'zustand/vanilla'

type PersonStoreState = {
  person: { firstName: string; lastName: string; email: string }
}

type PersonStoreActions = {
  setPerson: (nextPerson: PersonStoreState['person']) => void
}

type PersonStore = PersonStoreState & PersonStoreActions

const personStore = createStore<PersonStore>()((set) => ({
  person: {
    firstName: 'Barbara',
    lastName: 'Hepworth',
    email: 'bhepworth@sculpture.com',
  },
  setPerson: (person) => set({ person }),
}))

const $firstNameInput = document.getElementById(
  'first-name',
) as HTMLInputElement
const $lastNameInput = document.getElementById('last-name') as HTMLInputElement
const $emailInput = document.getElementById('email') as HTMLInputElement
const $result = document.getElementById('result') as HTMLDivElement

function handleFirstNameChange(event: Event) {
  personStore.getState().setPerson({
    ...personStore.getState().person,
    firstName: (event.target as any).value,
  })
}

function handleLastNameChange(event: Event) {
  personStore.getState().setPerson({
    ...personStore.getState().person,
    lastName: (event.target as any).value,
  })
}

function handleEmailChange(event: Event) {
  personStore.getState().setPerson({
    ...personStore.getState().person,
    email: (event.target as any).value,
  })
}

$firstNameInput.addEventListener('input', handleFirstNameChange)
$lastNameInput.addEventListener('input', handleLastNameChange)
$emailInput.addEventListener('input', handleEmailChange)

const render: Parameters<typeof personStore.subscribe>[0] = (state) => {
  $firstNameInput.value = state.person.firstName
  $lastNameInput.value = state.person.lastName
  $emailInput.value = state.person.email

  $result.innerHTML = `${state.person.firstName} ${state.person.lastName} (${state.person.email})`
}

render(personStore.getInitialState(), personStore.getInitialState())

personStore.subscribe(render)
```

--------------------------------

### Get persist options with getOptions

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/integrations/persisting-store-data.md

Retrieves the current persist options, for example to obtain the storage name.

```ts
useBoundStore.persist.getOptions().name
```

--------------------------------

### onRehydrateStorage listener

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/integrations/persisting-store-data.md

Example of using onRehydrateStorage to log hydration start and finish, including error handling.

```ts
export const useBoundStore = create(
  persist(
    (set, get) => ({
      // ...
    }),
    {
      // ...
      onRehydrateStorage: (state) => {
        console.log('hydration starts')

        // optional
        return (state, error) => {
          if (error) {
            console.log('an error happened during hydration', error)
          } else {
            console.log('hydration finished')
          }
        }
      },
    },
  ),
)
```

--------------------------------

### Unsoundness example: calling get during initial state

Source: https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/advanced-typescript.md

Demonstrates unsoundness in Zustand's types. This code compiles but throws `Uncaught TypeError: Cannot read properties of undefined (reading 'foo')` because `get` returns `undefined` before the initial state is created. Avoid calling `get` when creating the initial state.

```ts
import { create } from 'zustand'

const useBoundStore = create<{ foo: number }>()((_, get) => ({
  foo: get().foo,
}))
```

--------------------------------

### Conventional commit examples: type prefix and scope

Source: https://github.com/pmndrs/zustand/blob/main/CONTRIBUTING.md

Use these commit messages to comply with the Conventional Commits spec. The first example shows a simple type prefix (feat) followed by a colon, space, and a message starting with a lowercase letter. The second example shows a scope in parentheses after the type (fix(react)).

```text
feat: add a 'foo' type support

```

```text
fix(react): change the 'bar' parameter type

```

--------------------------------

### Zustand selector-based render optimization vs Jotai useAtom

Source: https://github.com/pmndrs/zustand/blob/main/docs/learn/getting-started/comparison.md

Zustand requires manual selectors for render optimization, while Jotai uses atom dependencies. The Zustand example shows selecting count and updateCount; the Jotai example uses useAtom to get count and updateCount.

```TypeScript
import { create } from 'zustand'

type State = {
  count: number
}

type Actions = {
  updateCount: (
    countCallback: (count: State['count']) => State['count'],
  ) => void
}

const useCountStore = create<State & Actions>((set) => ({
  count: 0,
  updateCount: (countCallback) =>
    set((state) => ({ count: countCallback(state.count) })),
}))

const Component = () => {
  const count = useCountStore((state) => state.count)
  const updateCount = useCountStore((state) => state.updateCount)
  // ...
}
```

```TypeScript
import { atom, useAtom } from 'jotai'

const countAtom = atom<number>(0)

const Component = () => {
  const [count, updateCount] = useAtom(countAtom)
  // ...
}
```

--------------------------------

### Filter actions with actionsDenylist single regex string

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/middlewares/devtools.md

Alternative form of actionsDenylist using a single regex string instead of an array. The example hides all actions starting with 'secret'.

```ts
const useStore = create<Store>()(
  devtools(
    (set) => ({
      // ... state and actions
    }),
    {
      name: 'MyStore',
      actionsDenylist: 'secret.*', // Hides all actions starting with 'secret'
    },
  ),
)
```

--------------------------------

### Selecting state with custom equality function

Source: https://github.com/pmndrs/zustand/blob/main/README.md

For more control over re-rendering, provide a custom equality function as the second argument to useBearStore. This example requires the use of createWithEqualityFn (see migration guide).

```jsx
const treats = useBearStore(
  (state) => state.treats,
  (oldTreats, newTreats) => compare(oldTreats, newTreats),
)
```

--------------------------------

### useStore basic usage

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/hooks/use-store.md

Shows the basic syntax of useStore, which takes a store and an optional selector function to return data based on current state.

```js
const someState = useStore(store, selectorFn)
```

--------------------------------

### Minimal create example showing inference failure

Source: https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/advanced-typescript.md

Minimal version of `create` showing why TypeScript cannot infer the state type. The generic `T` is invariant because it appears both in the return type and in the `get` parameter, causing inference to fail and `x` to be `unknown`.

```ts
declare const create: <T>(f: (get: () => T) => T) => T

const x = create((get) => ({
  foo: 0,
  bar: () => get(),
}))
// `x` is inferred as `unknown` instead of
// interface X {
//   foo: number,
//   bar: () => X
// }
```

--------------------------------

### Dynamic scoped vanilla stores in React with useCounterStore

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/hooks/use-store-with-equality-fn.md

The Tabs component uses useCounterStore with a dynamic key based on the current tab index, so each tab gets its own counter state. The App component wraps Tabs in CounterStoresProvider to provide the store context. This setup allows independent counter state per tab.

```tsx
function Tabs() {
  const [currentTabIndex, setCurrentTabIndex] = useState(0)
  const counterState = useCounterStore(
    `tab-${currentTabIndex}`,
    (state) => state,
  )

  return (
    <div style={{ fontFamily: 'monospace' }}>
      <div
        style={{
          display: 'flex',
          gap: '0.5rem',
          borderBottom: '1px solid salmon',
          paddingBottom: 4,
        }}
      >
        <button
          type="button"
          style={{
            border: '1px solid salmon',
            backgroundColor: '#fff',
            cursor: 'pointer',
          }}
          onClick={() => setCurrentTabIndex(0)}
        >
          Tab 1
        </button>
        <button
          type="button"
          style={{
            border: '1px solid salmon',
            backgroundColor: '#fff',
            cursor: 'pointer',
          }}
          onClick={() => setCurrentTabIndex(1)}
        >
          Tab 2
        </button>
        <button
          type="button"
          style={{
            border: '1px solid salmon',
            backgroundColor: '#fff',
            cursor: 'pointer',
          }}
          onClick={() => setCurrentTabIndex(2)}
        >
          Tab 3
        </button>
      </div>
      <div style={{ padding: 4 }}>
        Content of Tab {currentTabIndex + 1}
        <br /> <br />
        <button type="button" onClick={() => counterState.increment()}>
          Count: {counterState.count}
        </button>
      </div>
    </div>
  )
}
```

```tsx
export default function App() {
  return (
    <CounterStoresProvider>
      <Tabs />
    </CounterStoresProvider>
  )
}
```

--------------------------------

### createStore(stateCreatorFn)

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/apis/create-store.md

Creates a vanilla store that exposes API utilities: setState, getState, getInitialState, and subscribe.

```APIDOC
## createStore(stateCreatorFn)

### Description
Creates a vanilla store that exposes API utilities: `setState`, `getState`, `getInitialState`, and `subscribe`.

### Signature
```ts
createStore<T>()(stateCreatorFn: StateCreator<T, [], []>): StoreApi<T>
```

### Parameters
- `stateCreatorFn` (function) - Required - A function that takes `set`, `get`, and `store` as arguments. Usually returns an object with methods to expose. Note that `set`, `get`, and `store` cannot be used while this function is running, only after the store has been created.

### Returns
Returns a vanilla store that exposes API utilities: `setState`, `getState`, `getInitialState`, and `subscribe`.

### Usage

#### Updating state based on previous state
This example shows how to support **updater functions** within **actions**.

```tsx
import { createStore } from 'zustand/vanilla'

type AgeStoreState = { age: number }

type AgeStoreActions = {
  setAge: (
    nextAge:
      | AgeStoreState['age']
      | ((currentAge: AgeStoreState['age']) => AgeStoreState['age']),
  ) => void
}

type AgeStore = AgeStoreState & AgeStoreActions

const ageStore = createStore<AgeStore>()((set) => ({
  age: 42,
  setAge: (nextAge) =>
    set((state) => ({
      age: typeof nextAge === 'function' ? nextAge(state.age) : nextAge,
    })),
}))

function increment() {
  ageStore.getState().setAge((currentAge) => currentAge + 1)
}

const $yourAgeHeading = document.getElementById(
  'your-age',
) as HTMLHeadingElement
const $incrementBy3Button = document.getElementById(
  'increment-by-3',
) as HTMLButtonElement
const $incrementBy1Button = document.getElementById(
  'increment-by-1',
) as HTMLButtonElement

$incrementBy3Button.addEventListener('click', () => {
  increment()
  increment()
  increment()
})

$incrementBy1Button.addEventListener('click', () => {
  increment()
})

const render: Parameters<typeof ageStore.subscribe>[0] = (state) => {
  $yourAgeHeading.innerHTML = `Your age: ${state.age}`
}

render(ageStore.getInitialState(), ageStore.getInitialState())

ageStore.subscribe(render)
```

Here's the `html` code

```html
<h1 id="your-age"></h1>
<button id="increment-by-3" type="button">+3</button>
<button id="increment-by-1" type="button">+1</button>
```

#### Updating Primitives in State
State can hold any kind of JavaScript value. When you want to update built-in primitive values like numbers, strings, booleans, etc. you should directly assign new values to ensure updates are applied correctly, and avoid unexpected behaviors.

> [!NOTE]
> By default, `set` function performs a shallow merge. If you need to completely replace the state with a new one, use the `replace` parameter set to `true`

```ts
import { createStore } from 'zustand/vanilla'

type XStore = number

const xStore = createStore<XStore>()(() => 0)

const $dotContainer = document.getElementById('dot-container') as HTMLDivElement
const $dot = document.getElementById('dot') as HTMLDivElement

$dotContainer.addEventListener('pointermove', (event) => {
  xStore.setState(event.clientX, true)
})

const render: Parameters<typeof xStore.subscribe>[0] = (x) => {
  $dot.style.transform = `translate(${x}px, 0)`
}

render(xStore.getInitialState(), xStore.getInitialState())

xStore.subscribe(render)
```

Here's the `html` code

```html
<div
  id="dot-container"
  style="position: relative; width: 100vw; height: 100vh;"
>
  <div
    id="dot"
    style="position: absolute; background-color: red; border-radius: 50%; left: -10px; top: -10px; width: 20px; height: 20px;"
  ></div>
</div>
```
```

--------------------------------

### Persisted state example

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/integrations/persisting-store-data.md

Example of a persisted state object with a nested foo object.

```ts
{
  foo: {
    bar: 0,
  }
}
```

--------------------------------

### Creating dynamic global vanilla stores with factory functions

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/hooks/use-store-with-equality-fn.md

These two blocks together form the setup for dynamic global vanilla stores. The first creates a factory function that generates a counter store, and the second creates a factory that manages the creation and retrieval of counter stores per key, allowing each tab to have its own independent counter.

```ts
import { createStore } from 'zustand'

type CounterState = {
  count: number
}

type CounterActions = { increment: () => void }

type CounterStore = CounterState & CounterActions

const createCounterStore = () => {
  return createStore<CounterStore>()((set) => ({
    count: 0,
    increment: () => {
      set((state) => ({ count: state.count + 1 }))
    },
  }))
}
```

```ts
const defaultCounterStores = new Map<
  string,
  ReturnType<typeof createCounterStore>
>()

const createCounterStoreFactory = (
  counterStores: typeof defaultCounterStores,
) => {
  return (counterStoreKey: string) => {
    if (!counterStores.has(counterStoreKey)) {
      counterStores.set(counterStoreKey, createCounterStore())
    }
    return counterStores.get(counterStoreKey)!
  }
}

const getOrCreateCounterStoreByKey =
  createCounterStoreFactory(defaultCounterStores)
```

--------------------------------

### Full example: position tracker with partial persistence and HTML container

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/middlewares/persist.md

Complete code for a dot that follows the mouse and persists the context in localStorage. Includes the vanilla store, event listener, rendering logic, and the required HTML structure.

```TypeScript
import { createStore } from 'zustand/vanilla'
import { persist } from 'zustand/middleware'

type PositionStoreState = {
  context: {
    position: { x: number; y: number }
  }
}

type PositionStoreActions = {
  actions: {
    setPosition: (
      nextPosition: PositionStoreState['context']['position'],
    ) => void
  }
}

type PositionStore = PositionStoreState & PositionStoreActions

const positionStore = createStore<PositionStore>()(
  persist(
    (set) => ({
      context: {
        position: { x: 0, y: 0 },
      },
      actions: {
        setPosition: (position) => set({ context: { position } }),
      },
    }),
    {
      name: 'position-storage',
      partialize: (state) => ({ context: state.context }),
    },
  ),
)

const $dotContainer = document.getElementById('dot-container') as HTMLDivElement
const $dot = document.getElementById('dot') as HTMLDivElement

$dotContainer.addEventListener('pointermove', (event) => {
  positionStore.getState().actions.setPosition({
    x: event.clientX,
    y: event.clientY,
  })
})

const render: Parameters<typeof positionStore.subscribe>[0] = (state) => {
  $dot.style.transform = `translate(${state.context.position.x}px, ${state.context.position.y}px)`
}

render(positionStore.getState(), positionStore.getState())

positionStore.subscribe(render)
```

```HTML
<div
  id="dot-container"
  style="position: relative; width: 100vw; height: 100vh;"
>
  <div
    id="dot"
    style="position: absolute; background-color: red; border-radius: 50%; left: -10px; top: -10px; width: 20px; height: 20px;"
  ></div>
</div>
```

--------------------------------

### Subscribe to hydration start with onHydrate

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/integrations/persisting-store-data.md

Registers a listener called when hydration starts; returns an unsubscribe function.

```ts
const unsub = useBoundStore.persist.onHydrate((state) => {
  console.log('hydration starts')
})

// later on...
unsub()
```

--------------------------------

### Complete example: scoped vanilla store with Tabs

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/hooks/use-store.md

Full code combining store creation, factory, and Tabs component in a single App component. Demonstrates the complete pattern for using a scoped vanilla store in React.

```TSX
import { useState } from 'react'
import { createStore, useStore } from 'zustand'

type CounterState = {
  count: number
}

type CounterActions = { increment: () => void }

type CounterStore = CounterState & CounterActions

const createCounterStore = () => {
  return createStore<CounterStore>()((set) => ({
    count: 0,
    increment: () => {
      set((state) => ({ count: state.count + 1 }))
    },
  }))
}

const defaultCounterStores = new Map<
  string,
  ReturnType<typeof createCounterStore>
>()

const createCounterStoreFactory = (
  counterStores: typeof defaultCounterStores,
) => {
  return (counterStoreKey: string) => {
    if (!counterStores.has(counterStoreKey)) {
      counterStores.set(counterStoreKey, createCounterStore())
    }
    return counterStores.get(counterStoreKey)!
  }
}

const getOrCreateCounterStoreByKey =
  createCounterStoreFactory(defaultCounterStores)

export default function App() {
  const [currentTabIndex, setCurrentTabIndex] = useState(0)
  const counterState = useStore(
    getOrCreateCounterStoreByKey(`tab-${currentTabIndex}`),
  )

  return (
    <div style={{ fontFamily: 'monospace' }}>
      <div
        style={{
          display: 'flex',
          gap: '0.5rem',
          borderBottom: '1px solid salmon',
          paddingBottom: 4,
        }}
      >
        <button
          type="button"
          style={{
            border: '1px solid salmon',
            backgroundColor: '#fff',
            cursor: 'pointer',
          }}
          onClick={() => setCurrentTabIndex(0)}
        >
          Tab 1
        </button>
        <button
          type="button"
          style={{
            border: '1px solid salmon',
            backgroundColor: '#fff',
            cursor: 'pointer',
          }}
          onClick={() => setCurrentTabIndex(1)}
        >
          Tab 2
        </button>
        <button
          type="button"
          style={{
            border: '1px solid salmon',
            backgroundColor: '#fff',
            cursor: 'pointer',
          }}
          onClick={() => setCurrentTabIndex(2)}
        >
          Tab 3
        </button>
      </div>
      <div style={{ padding: 4 }}>
        Content of Tab {currentTabIndex + 1}
        <br /> <br />
        <button type="button" onClick={() => counterState.increment()}>
          Count: {counterState.count}
        </button>
      </div>
    </div>
  )
}
```

--------------------------------

### Create a store with create

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/apis/create.md

Basic usage of `create` to create a React Hook with API utilities attached.

```javascript
const useSomeStore = create(stateCreatorFn)
```

--------------------------------

### Zustand vanilla store with mutating input handlers (broken example)

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/apis/create-store.md

A complete example of a Zustand vanilla store with a person object and input handlers that mutate the state directly. The HTML provides the corresponding form elements and result paragraph. This example is shown as broken because the oninput handlers mutate the state, so the screen does not update.

```ts
import { createStore } from 'zustand/vanilla'

type PersonStoreState = {
  person: { firstName: string; lastName: string; email: string }
}

type PersonStoreActions = {
  setPerson: (nextPerson: PersonStoreState['person']) => void
}

type PersonStore = PersonStoreState & PersonStoreActions

const personStore = createStore<PersonStore>()((set) => ({
  person: {
    firstName: 'Barbara',
    lastName: 'Hepworth',
    email: 'bhepworth@sculpture.com',
  },
  setPerson: (person) => set({ person }),
}))

const $firstNameInput = document.getElementById(
  'first-name',
) as HTMLInputElement
const $lastNameInput = document.getElementById('last-name') as HTMLInputElement
const $emailInput = document.getElementById('email') as HTMLInputElement
const $result = document.getElementById('result') as HTMLDivElement

function handleFirstNameChange(event: Event) {
  personStore.getState().person.firstName = (event.target as any).value
}

function handleLastNameChange(event: Event) {
  personStore.getState().person.lastName = (event.target as any).value
}

function handleEmailChange(event: Event) {
  personStore.getState().person.email = (event.target as any).value
}

$firstNameInput.addEventListener('input', handleFirstNameChange)
$lastNameInput.addEventListener('input', handleLastNameChange)
$emailInput.addEventListener('input', handleEmailChange)

const render: Parameters<typeof personStore.subscribe>[0] = (state) => {
  $firstNameInput.value = state.person.firstName
  $lastNameInput.value = state.person.lastName
  $emailInput.value = state.person.email

  $result.innerHTML = `${state.person.firstName} ${state.person.lastName} (${state.person.email})`
}

render(personStore.getInitialState(), personStore.getInitialState())

personStore.subscribe(render)
```

```html
<label style="display: block">
  First name:
  <input id="first-name" />
</label>
<label style="display: block">
  Last name:
  <input id="last-name" />
</label>
<label style="display: block">
  Email:
  <input id="email" />
</label>
<p id="result"></p>
```

--------------------------------

### Full implementation of tabbed counter stores

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/hooks/use-store-with-equality-fn.md

A complete example showing store creation, a factory function for scoped stores, and the App component using useStoreWithEqualityFn.

```tsx
import { useState } from 'react'
import { createStore } from 'zustand'
import { useStoreWithEqualityFn } from 'zustand/traditional'
import { shallow } from 'zustand/shallow'

type CounterState = {
  count: number
}

type CounterActions = { increment: () => void }

type CounterStore = CounterState & CounterActions

const createCounterStore = () => {
  return createStore<CounterStore>()((set) => ({
    count: 0,
    increment: () => {
      set((state) => ({ count: state.count + 1 }))
    },
  }))
}

const defaultCounterStores = new Map<
  string,
  ReturnType<typeof createCounterStore>
>()

const createCounterStoreFactory = (
  counterStores: typeof defaultCounterStores,
) => {
  return (counterStoreKey: string) => {
    if (!counterStores.has(counterStoreKey)) {
      counterStores.set(counterStoreKey, createCounterStore())
    }
    return counterStores.get(counterStoreKey)!
  }
}

const getOrCreateCounterStoreByKey =
  createCounterStoreFactory(defaultCounterStores)

export default function App() {
  const [currentTabIndex, setCurrentTabIndex] = useState(0)
  const counterState = useStoreWithEqualityFn(
    getOrCreateCounterStoreByKey(`tab-${currentTabIndex}`),
    (state) => state,
    shallow,
  )

  return (
    <div style={{ fontFamily: 'monospace' }}>
      <div
        style={{
          display: 'flex',
          gap: '0.5rem',
          borderBottom: '1px solid salmon',
          paddingBottom: 4,
        }}
      >
        <button
          type="button"
          style={{
            border: '1px solid salmon',
            backgroundColor: '#fff',
            cursor: 'pointer',
          }}
          onClick={() => setCurrentTabIndex(0)}
        >
          Tab 1
        </button>
        <button
          type="button"
          style={{
            border: '1px solid salmon',
            backgroundColor: '#fff',
            cursor: 'pointer',
          }}
          onClick={() => setCurrentTabIndex(1)}
        >
          Tab 2
        </button>
        <button
          type="button"
          style={{
            border: '1px solid salmon',
            backgroundColor: '#fff',
            cursor: 'pointer',
          }}
          onClick={() => setCurrentTabIndex(2)}
        >
          Tab 3
        </button>
      </div>
      <div style={{ padding: 4 }}>
        Content of Tab {currentTabIndex + 1}
        <br /> <br />
        <button type="button" onClick={() => counterState.increment()}>
          Count: {counterState.count}
        </button>
      </div>
    </div>
  )
}
```

--------------------------------

### Simple persist middleware example in TypeScript

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/integrations/persisting-store-data.md

TypeScript version of the persist middleware example. It defines a `BearStore` type that is passed to `create`, ensuring type safety for state and actions.

```ts
import { create } from 'zustand'
import { persist, createJSONStorage } from 'zustand/middleware'

type BearStore = {
  bears: number
  addABear: () => void
}

export const useBearStore = create<BearStore>()(
  persist(
    (set, get) => ({
      bears: 0,
      addABear: () => set({ bears: get().bears + 1 }),
    }),
    {
      name: 'food-storage', // name of the item in the storage (must be unique)
      storage: createJSONStorage(() => sessionStorage), // (optional) by default, 'localStorage' is used
    },
  ),
)
```

--------------------------------

### Set up vanilla store with persist middleware

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/middlewares/persist.md

Creates a vanilla store with a position state and setPosition action, wrapped in persist middleware to store in localStorage under the name 'position-storage'.

```TypeScript
import { createStore } from 'zustand/vanilla'
import { persist } from 'zustand/middleware'

type PositionStoreState = { position: { x: number; y: number } }

type PositionStoreActions = {
  setPosition: (nextPosition: PositionStoreState['position']) => void
}

type PositionStore = PositionStoreState & PositionStoreActions

const positionStore = createStore<PositionStore>()(
  persist(
    (set) => ({
      position: { x: 0, y: 0 },
      setPosition: (position) => set({ position }),
    }),
    { name: 'position-storage' },
  ),
)
```

--------------------------------

### Invariant generic inference example with createFoo

Source: https://github.com/pmndrs/zustand/blob/main/docs/learn/guides/advanced-typescript.md

Another simple example of invariant generic inference. `x` is inferred as `unknown` instead of `string` because the generic `T` appears both as input and output of the function.

```ts
const createFoo = {} as <T>(f: (t: T) => T) => T
const x = createFoo((_) => 'hello')
```

--------------------------------

### createStore basic usage

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/apis/create-store.md

Shows the basic call signature for createStore, which takes a state creator function and returns a vanilla store.

```js
const someStore = createStore(stateCreatorFn)
```

--------------------------------

### setState replace flag examples

Source: https://github.com/pmndrs/zustand/blob/main/docs/reference/migrations/migrating-to-v5.md

Examples of valid and invalid setState calls with the replace flag. Partial updates are valid without replace, complete replacements are valid with replace: true, and incomplete replacements like store.setState({}, true) are now invalid.

```typescript
// Partial state update (valid)
store.setState({ key: 'value' })

// Complete state replacement (valid)
store.setState({ key: 'value' }, true)

// Incomplete state replacement (invalid)
store.setState({}, true) // Error
```
Tokens:
Raw