Zustand

https://zustand.docs.pmnd.rs/
Admin
Zustand is a small, fast, and scalable state management solution for React with a simple hook-based...
Tokens:102,697
Snippets:805
Trust Score:8.4
Update:7 hours ago
Show doc for...
Tokens:
Raw
### Configure tsconfig.json for Next.js

Source: https://zustand.docs.pmnd.rs/learn/guides/nextjs.html

Example tsconfig.json for a Next.js project. Remove all comments from the file before use.

```json
// tsconfig.json
{
  "compilerOptions": {
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}
```

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

### Example with as Parameters workaround for dynamic replace flag

Source: https://zustand.docs.pmnd.rs/learn/guides/advanced-typescript.html

Full example showing how to use the as Parameters workaround with a Zustand store. Ensures type safety when the replace flag is dynamic.

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

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

const useBearStore = create<BearState>()((set) => ({
  bears: 0,
  increase: (by) => set((state) => ({ bears: state.bears + by })),
}))

const replaceFlag = Math.random() > 0.5
const args = [{ bears: 5 }, replaceFlag] as Parameters<typeof useBearStore.setState>
useBearStore.setState(...args) // Using the workaround
```

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

### Install Zustand via NPM

Source: https://zustand.docs.pmnd.rs/learn/getting-started/introduction

Install the Zustand package using NPM. Any package manager of your choice can be used instead.

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

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

### Complete example: Zustand store with persist and migration

Source: https://zustand.docs.pmnd.rs/reference/middlewares/persist.html

Full code combining the store creation with persist middleware, migration from version 0 to 1, mouse tracking, and rendering. Includes the tutorial-only localStorage setup.

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

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

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 }, // version 0: just x: 0, y: 0
      setPosition: (position) => set({ position }),
    }),
    {
      name: 'position-storage',
      version: 1,
      migrate: (persisted: any, version) => {
        if (version === 0) {
          persisted.position = { x: persisted.x, y: persisted.y }
          delete persisted.x
          delete persisted.y
        }

        return persisted
      },
    },
  ),
)

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)
```

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

### Run the server

Source: https://zustand.docs.pmnd.rs/learn/guides/ssr-and-hydration.html

Start the compiled Node.js server.

```bash
node server.js
```

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

### Jest setup file with jest-dom

Source: https://zustand.docs.pmnd.rs/learn/guides/testing.html

Imports `@testing-library/jest-dom` to extend Jest matchers. Place in `setup-jest.ts`.

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

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

### Install Immer

Source: https://zustand.docs.pmnd.rs/reference/integrations/immer-middleware.html

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

```bash
npm install immer
```

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

### Complete MovingDot Example with useStore

Source: https://zustand.docs.pmnd.rs/reference/hooks/use-store.html

Full example combining the position store, MovingDot component, and App component. Shows how to use useStore with a vanilla store in React.

```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 />
}
```

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

### Install zustand with deno

Source: https://zustand.docs.pmnd.rs/

Install the zustand package using deno.

```shell
deno add npm:zustand
```

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

### Install zustand with bun

Source: https://zustand.docs.pmnd.rs/

Install the zustand package using bun.

```shell
bun add zustand
```

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

### Configure Vitest with globals, jsdom, and setup file

Source: https://zustand.docs.pmnd.rs/learn/guides/testing.html

Create a vitest.config.ts file that merges Vite config and sets test options: globals true, environment jsdom, and setupFiles pointing to setup-vitest.ts.

```typescript
// 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'],
      },
    }),
  ),
)
```

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

### Hypothetical middleware that mutates the store

Source: https://zustand.docs.pmnd.rs/learn/guides/advanced-typescript.html

Example of a middleware that adds a property to the store. Shows how a middleware can mutate the store and how to type it using a higher-kinded mutator.

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

const foo = (f, bar) => (set, get, store) => {
  store.foo = bar
  return f(set, get, store)
}

const useBearStore = create(foo(() => ({ bears: 0 }), 'hello'))
console.log(useBearStore.foo.toUpperCase())
```

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

### Setup Vitest with jest-dom and Zustand mock

Source: https://zustand.docs.pmnd.rs/learn/guides/testing.html

Create a setup-vitest.ts file to import jest-dom matchers and mock Zustand. Without globals enabled, add `import { vi } from 'vitest'` at the top.

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

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

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

### Complete example: BearProvider with HookConsumer

Source: https://zustand.docs.pmnd.rs/learn/guides/initialize-state-with-props.html

Shows App2 rendering BearProvider with bears={2} and a HookConsumer child. This is the complete example combining the provider wrapper and custom hook consumer.

```tsx
// Provider wrapper & custom hook consumer
function App2() {
  return (
    <BearProvider bears={2}>
      <HookConsumer />
    </BearProvider>
  )
}
```

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

### Example squares array after filling the board

Source: https://zustand.docs.pmnd.rs/learn/guides/tutorial-tic-tac-toe.html

Shows the shape of the squares array after some squares are filled. Each entry is 'X', 'O', or null for an empty square.

```js
const squares = ['O', null, 'X', 'X', 'X', 'O', 'O', null, null]
```

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

### Install zustand with yarn

Source: https://zustand.docs.pmnd.rs/

Install the zustand package using yarn.

```shell
yarn add zustand
```

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

### Wrap Next.js App Router root layout with CounterStoreProvider

Source: https://zustand.docs.pmnd.rs/learn/guides/nextjs.html

RootLayout component for the App Router that wraps children with CounterStoreProvider, making the Zustand store available throughout the application.

```tsx
// src/app/layout.tsx
import type { Metadata } from 'next'
import { Inter } from 'next/font/google'
import './globals.css'

import { CounterStoreProvider } from '@/providers/counter-store-provider'

const inter = Inter({ subsets: ['latin'] })

export const metadata: Metadata = {
  title: 'Create Next App',
  description: 'Generated by create next app',
}

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode
}>) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <CounterStoreProvider>{children}</CounterStoreProvider>
      </body>
    </html>
  )
}
```

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

### Install zustand with npm

Source: https://zustand.docs.pmnd.rs/

Install the zustand package using npm.

```shell
npm install zustand
```

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

### Create useCounterStore with Zustand create

Source: https://zustand.docs.pmnd.rs/learn/guides/testing.html

Create a useCounterStore hook using Zustand's create and the counterStoreCreator. This store is used in the testing examples.

```typescript
// stores/use-counter-store.ts
import { create } from 'zustand'

import { type CounterStore, counterStoreCreator } from '../shared/counter-store-creator'

export const useCounterStore = create<CounterStore>()(counterStoreCreator)
```

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

### Install zustand with pnpm

Source: https://zustand.docs.pmnd.rs/

Install the zustand package using pnpm.

```shell
pnpm add zustand
```

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

### Complete example without useShallow

Source: https://zustand.docs.pmnd.rs/reference/hooks/use-shallow.html

Full code showing the store, UpdateBabyBearMeal, BearNames, and App components. BearNames re-renders on every state change.

```javascript
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 />
    </>
  )
}
```

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

### HTML form for person store example

Source: https://zustand.docs.pmnd.rs/reference/apis/create-store.html

This HTML provides the input fields and result paragraph used by the person store example. It is required for the JavaScript to attach event listeners and display the result.

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

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

### Complete tabbed counter example with useStoreWithEqualityFn and shallow

Source: https://zustand.docs.pmnd.rs/reference/hooks/use-store-with-equality-fn.html

Full example combining store creation, a store factory keyed by tab, and a React component using useStoreWithEqualityFn with shallow equality. Each tab maintains its own counter state.

```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>
  )
}
```

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

### Wrap Next.js Pages Router app with CounterStoreProvider in _app.tsx

Source: https://zustand.docs.pmnd.rs/learn/guides/nextjs.html

Custom App component for the Pages Router that wraps all pages with CounterStoreProvider, making the Zustand store available throughout the application.

```tsx
// src/_app.tsx
import type { AppProps } from 'next/app'

import { CounterStoreProvider } from '@/providers/counter-store-provider'

export default function App({ Component, pageProps }: AppProps) {
  return (
    <CounterStoreProvider>
      <Component {...pageProps} />
    </CounterStoreProvider>
  )
}
```

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

### Render HomePage in Next.js App Router page

Source: https://zustand.docs.pmnd.rs/learn/guides/nextjs.html

Default export for the App Router page that renders the HomePage component. The store is provided globally via layout.tsx.

```tsx
// src/app/page.tsx
import { HomePage } from '@/components/pages/home-page'

export default function Home() {
  return <HomePage />
}
```

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

### Render HomePage in Next.js Pages Router index page

Source: https://zustand.docs.pmnd.rs/learn/guides/nextjs.html

Default export for the Pages Router index route that renders the HomePage component. The store is provided globally via _app.tsx.

```tsx
// src/pages/index.tsx
import { HomePage } from '@/components/pages/home-page'

export default function Home() {
  return <HomePage />
}
```

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

### setState replace flag usage examples

Source: https://zustand.docs.pmnd.rs/reference/migrations/migrating-to-v5.html

Partial updates and complete state replacements are valid; an incomplete state replacement with replace true is invalid and causes an error.

```javascript
// 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
```

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

### Define a vanilla store with createStore

Source: https://zustand.docs.pmnd.rs/learn/guides/auto-generating-selectors.html

Example vanilla store definition using createStore from zustand. The store has a bears property and increase and increment actions.

```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 })),
}))
```

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

### Jest configuration with ts-jest and jsdom

Source: https://zustand.docs.pmnd.rs/learn/guides/testing.html

Configures Jest to use `ts-jest` preset, `jsdom` test environment, and the setup file. Place in `jest.config.ts`. Requires `ts-jest` and `ts-node` packages for TypeScript.

```typescript
// jest.config.ts
import type { JestConfigWithTsJest } from 'ts-jest'

const config: JestConfigWithTsJest = {
  preset: 'ts-jest',
  testEnvironment: 'jsdom',
  setupFilesAfterEnv: ['./setup-jest.ts'],
}

export default config
```

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

### Complete position tracker with persist middleware

Source: https://zustand.docs.pmnd.rs/reference/middlewares/persist.html

Combines the store creation, pointer event handling, and rendering logic into a single script for the position tracker example.

```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)
```

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

### Unsoundness example: calling get during initial state creation

Source: https://zustand.docs.pmnd.rs/learn/guides/advanced-typescript.html

This code compiles but throws a TypeError at runtime because get returns undefined before the initial state is created. Avoid calling get when creating the initial state.

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

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

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

### Currying workaround example with withError

Source: https://zustand.docs.pmnd.rs/learn/guides/advanced-typescript.html

This example illustrates the scenario that the currying workaround addresses, referencing microsoft/TypeScript#10571.

```typescript
declare const withError: <T, E>(
  p: Promise<T>,
) => Promise<[error: undefined, value: T] | [error: E, value: undefined]>
declare const doSomething: () => Promise<string>

const main = async () => {
  let [error, value] = await withError(doSomething())
}
```

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

### Simple invariant generic example with createFoo

Source: https://zustand.docs.pmnd.rs/learn/guides/advanced-typescript.html

Another example of invariant generic inference failure: x is inferred as unknown instead of string.

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

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

### Deeply nested state type definition

Source: https://zustand.docs.pmnd.rs/learn/guides/updating-state.html

Defines a state shape with a deeply nested object. Use this as a starting point for examples that update nested state immutably.

```typescript
type State = {
  deep: {
    nested: {
      obj: { count: number }
    }
  }
}
```

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

### Create a per-route store in Next.js App Router page

Source: https://zustand.docs.pmnd.rs/learn/guides/nextjs.html

Alternative App Router page that wraps HomePage with CounterStoreProvider to create a store per route. Use only when a store per route is required.

```tsx
// src/app/page.tsx
import { CounterStoreProvider } from '@/providers/counter-store-provider'
import { HomePage } from '@/components/pages/home-page'

export default function Home() {
  return (
    <CounterStoreProvider>
      <HomePage />
    </CounterStoreProvider>
  )
}
```

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

### Use devtools and persist middlewares inside create in TypeScript

Source: https://zustand.docs.pmnd.rs/learn/guides/advanced-typescript.html

Use middlewares immediately inside `create` to enable contextual inference. This example wraps `persist` with `devtools` and provides a `name` option for persistence.

```typescript
import { create } from 'zustand'
import { devtools, persist } from 'zustand/middleware'

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

const useBearStore = create<BearState>()(
  devtools(
    persist(
      (set) => ({
        bears: 0,
        increase: (by) => set((state) => ({ bears: state.bears + by })),
      }),
      { name: 'bearStore' },
    ),
  ),
)
```

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

### Minimal create function showing invariant type inference failure

Source: https://zustand.docs.pmnd.rs/learn/guides/advanced-typescript.html

This minimal version of create demonstrates that TypeScript infers T as unknown when the generic is invariant. The type of f is (get: () => T) => T, making T both covariant and contravariant.

```typescript
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
// }
```

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

### Create a per-route store in Next.js Pages Router index page

Source: https://zustand.docs.pmnd.rs/learn/guides/nextjs.html

Alternative Pages Router index page that wraps HomePage with CounterStoreProvider to create a store per route. Use only when a store per route is required.

```tsx
// src/pages/index.tsx
import { CounterStoreProvider } from '@/providers/counter-store-provider'
import { HomePage } from '@/components/pages/home-page'

export default function Home() {
  return (
    <CounterStoreProvider>
      <HomePage />
    </CounterStoreProvider>
  )
}
```

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

### Custom middleware wrapper requires advanced types in TypeScript

Source: https://zustand.docs.pmnd.rs/learn/guides/advanced-typescript.html

Using a custom middleware wrapper like `myMiddlewares` instead of placing middlewares directly inside `create` requires more advanced types. This example shows the pattern that may not infer correctly.

```typescript
import { create } from 'zustand'
import { devtools, persist } from 'zustand/middleware'

const myMiddlewares = (f) => devtools(persist(f, { name: 'bearStore' }))

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

const useBearStore = create<BearState>()(
  myMiddlewares((set) => ({
    bears: 0,
    increase: (by) => set((state) => ({ bears: state.bears + by })),
  })),
)
```

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

### Create a Zustand store with create and set

Source: https://zustand.docs.pmnd.rs/learn/getting-started/introduction

Define a store hook using create. The set function merges state, so you can update individual fields without spreading the entire state.

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

const useBear = create((set) => ({
  bears: 0,
  increasePopulation: () => set((state) => ({ bears: state.bears + 1 })),
  removeAllBears: () => set({ bears: 0 }),
  updateBears: (newBears) => set({ bears: newBears }),
}))
```

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

### Complete example: Tabs with independent counters using useStore

Source: https://zustand.docs.pmnd.rs/reference/hooks/use-store.html

Full code combining store creation, factory, and App component with tabs and counters. Each tab has its own counter state managed via useStore.

```javascript
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>
  )
}
```

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

### Extract store state type with ExtractState in Zustand

Source: https://zustand.docs.pmnd.rs/learn/guides/beginner-typescript.html

Uses the built-in ExtractState helper to get the full type of the store's state and actions. Useful for tests, utility functions, or component props without manually redefining types.

```typescript
// store.ts
import { create, type ExtractState } from 'zustand'

export const useBearStore = create((set) => ({
  bears: 3,
  food: 'honey',
  increase: (by: number) => set((s) => ({ bears: s.bears + by })),
}))

// Extract the type of the whole store state
export type BearState = ExtractState<typeof useBearStore>
```

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

### Create a Zustand store per request with createStore

Source: https://zustand.docs.pmnd.rs/learn/guides/nextjs.html

Factory function that creates a new Zustand store for each request. Use this to avoid sharing module state across requests in Next.js.

```typescript
// src/stores/counter-store.ts
import { createStore } from 'zustand/vanilla'

export type CounterState = {
  count: number
}

export type CounterActions = {
  decrementCount: () => void
  incrementCount: () => void
}

export type CounterStore = CounterState & CounterActions

export const defaultInitState: CounterState = {
  count: 0,
}

export const createCounterStore = (initState: CounterState = defaultInitState) => {
  return createStore<CounterStore>()((set) => ({
    ...initState,
    decrementCount: () => set((state) => ({ count: state.count - 1 })),
    incrementCount: () => set((state) => ({ count: state.count + 1 })),
  }))
}
```

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

### Subscribe to Hydration Start with onHydrate

Source: https://zustand.docs.pmnd.rs/reference/integrations/persisting-store-data.html

Registers a listener that is called when the hydration process starts. Returns an unsubscribe function.

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

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

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

### Full code for dot following mouse with partial persistence

Source: https://zustand.docs.pmnd.rs/reference/middlewares/persist.html

Complete example combining store creation, pointer tracking, and rendering to create a dot that follows the mouse and persists the context in localStorage.

```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)
```

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

### Use Zustand store in a Next.js App Router client component

Source: https://zustand.docs.pmnd.rs/learn/guides/nextjs.html

HomePage component for the App Router that reads count and increment/decrement actions from useCounterStore. Requires the 'use client' directive and the CounterStoreProvider in layout.tsx or at the page level.

```tsx
// src/components/pages/home-page.tsx
'use client'

import { useCounterStore } from '@/providers/counter-store-provider'

export const HomePage = () => {
  const { count, incrementCount, decrementCount } = useCounterStore((state) => state)

  return (
    <div>
      Count: {count}
      <hr />
      <button type="button" onClick={incrementCount}>
        Increment Count
      </button>
      <button type="button" onClick={decrementCount}>
        Decrement Count
      </button>
    </div>
  )
}
```

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

### Persisted state example with nested foo object

Source: https://zustand.docs.pmnd.rs/reference/integrations/persisting-store-data.html

Example of persisted state containing a nested foo object with only bar. Used to illustrate shallow merge behavior.

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

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

### Complete example: persist position with manual hydration

Source: https://zustand.docs.pmnd.rs/reference/middlewares/persist.html

Combines store creation with persist middleware, pointer event handling, delayed rehydration, and rendering into a single script.

```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',
      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)
```

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

### Current Zustand store state example with nested foo object

Source: https://zustand.docs.pmnd.rs/reference/integrations/persisting-store-data.html

Example of current store state containing a nested foo object with bar and baz. Used to illustrate shallow merge behavior.

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

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

### TypeScript persist example with BearStore type

Source: https://zustand.docs.pmnd.rs/reference/integrations/persisting-store-data.html

TypeScript version of the simple persist example, using a BearStore type for the store state. The name option is required and must be unique; storage defaults to localStorage if omitted.

```typescript
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
    },
  ),
)
```

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

### Provide the store via BearContext.Provider in App

Source: https://zustand.docs.pmnd.rs/learn/guides/initialize-state-with-props.html

Creates the store once with useState(() => createBearStore()) and passes it to BearContext.Provider. The provider wraps BasicConsumer so it can access the store.

```tsx
// Provider implementation
import { useState } from 'react'

function App() {
  const [store] = useState(() => createBearStore())
  return (
    <BearContext.Provider value={store}>
      <BasicConsumer />
    </BearContext.Provider>
  )
}
```

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

### Add handlePlay and pass props to Board in Game component

Source: https://zustand.docs.pmnd.rs/learn/guides/tutorial-tic-tac-toe.html

Define handlePlay inside Game and pass xIsNext, currentSquares, and handlePlay as props to Board. The handlePlay body is a placeholder to be implemented later.

```javascript
export default function Game() {
  const history = useGameStore((state) => state.history)
  const setHistory = useGameStore((state) => state.setHistory)
  const xIsNext = useGameStore((state) => state.xIsNext)
  const setXIsNext = useGameStore((state) => state.setXIsNext)
  const currentSquares = history[history.length - 1]

  function handlePlay(nextSquares) {
    // TODO
  }

  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'row',
        fontFamily: 'monospace',
      }}
    >
      <div>
        <Board xIsNext={xIsNext} squares={currentSquares} onPlay={handlePlay} />
      </div>
      <div style={{ marginLeft: '1rem' }}>
        <ol>{/*TODO*/}</ol>
      </div>
    </div>
  )
}
```

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

### Mock Zustand with Vitest

Source: https://zustand.docs.pmnd.rs/learn/guides/testing.html

Create a __mocks__/zustand.ts file to mock Zustand stores and reset them after each test. Ensure the __mocks__ directory is placed correctly relative to the Vitest root. Without globals enabled, add `import { afterEach, vi } from 'vitest'` at the top.

```typescript
// __mocks__/zustand.ts
import { act } from '@testing-library/react'
import type * as ZustandExportedTypes from 'zustand'
export * from 'zustand'

const { create: actualCreate, createStore: actualCreateStore } =
  await vi.importActual<typeof ZustandExportedTypes>('zustand')

// a variable to hold reset functions for all stores declared in the app
export const storeResetFns = new Set<() => void>()

const createUncurried = <T>(stateCreator: ZustandExportedTypes.StateCreator<T>) => {
  const store = actualCreate(stateCreator)
  const initialState = store.getInitialState()
  storeResetFns.add(() => {
    store.setState(initialState, true)
  })
  return store
}

// when creating a store, we get its initial state, create a reset function and add it in the set
export const create = (<T>(stateCreator: ZustandExportedTypes.StateCreator<T>) => {
  console.log('zustand create mock')

  // to support curried version of create
  return typeof stateCreator === 'function' ? createUncurried(stateCreator) : createUncurried
}) as typeof ZustandExportedTypes.create

const createStoreUncurried = <T>(stateCreator: ZustandExportedTypes.StateCreator<T>) => {
  const store = actualCreateStore(stateCreator)
  const initialState = store.getInitialState()
  storeResetFns.add(() => {
    store.setState(initialState, true)
  })
  return store
}

// when creating a store, we get its initial state, create a reset function and add it in the set
export const createStore = (<T>(stateCreator: ZustandExportedTypes.StateCreator<T>) => {
  console.log('zustand createStore mock')

  // to support curried version of createStore
  return typeof stateCreator === 'function'
    ? createStoreUncurried(stateCreator)
    : createStoreUncurried
}) as typeof ZustandExportedTypes.createStore

// reset all stores after each test run
afterEach(() => {
  act(() => {
    storeResetFns.forEach((resetFn) => {
      resetFn()
    })
  })
})
```

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

### Wrap the context provider in a BearProvider component

Source: https://zustand.docs.pmnd.rs/learn/guides/initialize-state-with-props.html

Accepts BearProps and children, creates the store once with useState(() => createBearStore(props)), and provides it to children. Use this to avoid repeating provider setup.

```tsx
// Provider wrapper
import { useState } from 'react'

type BearProviderProps = React.PropsWithChildren<BearProps>

function BearProvider({ children, ...props }: BearProviderProps) {
  const [store] = useState(() => createBearStore(props))
  return <BearContext.Provider value={store}>{children}</BearContext.Provider>
}
```

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

### Use Zustand store in a Next.js Pages Router page component

Source: https://zustand.docs.pmnd.rs/learn/guides/nextjs.html

HomePage component for the Pages Router that reads count and increment/decrement actions from useCounterStore. Requires the CounterStoreProvider to be set up in _app.tsx or at the page level.

```tsx
// src/components/pages/home-page.tsx
import { useCounterStore } from '@/providers/counter-store-provider'

export const HomePage = () => {
  const { count, incrementCount, decrementCount } = useCounterStore((state) => state)

  return (
    <div>
      Count: {count}
      <hr />
      <button type="button" onClick={incrementCount}>
        Increment Count
      </button>
      <button type="button" onClick={decrementCount}>
        Decrement Count
      </button>
    </div>
  )
}
```

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

### Zustand store with currentMove state

Source: https://zustand.docs.pmnd.rs/learn/guides/tutorial-tic-tac-toe.html

Defines the Zustand store with history, currentMove, and xIsNext state, along with their setters. currentMove starts at 0.

```js
const useGameStore = create(
  combine({ history: [Array(9).fill(null)], currentMove: 0, xIsNext: true }, (set) => {
    return {
      setHistory: (nextHistory) => {
        set((state) => ({
          history: typeof nextHistory === 'function' ? nextHistory(state.history) : nextHistory,
        }))
      },
      setCurrentMove: (nextCurrentMove) => {
        set((state) => ({
          currentMove:
            typeof nextCurrentMove === 'function'
              ? nextCurrentMove(state.currentMove)
              : nextCurrentMove,
        }))
      },
      setXIsNext: (nextXIsNext) => {
        set((state) => ({
          xIsNext: typeof nextXIsNext === 'function' ? nextXIsNext(state.xIsNext) : nextXIsNext,
        }))
      },
    }
  }),
)
```

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

### Attempt to implement createFoo

Source: https://zustand.docs.pmnd.rs/learn/guides/advanced-typescript.html

This shows that createFoo cannot be implemented because it requires producing a value of type T without knowing T.

```typescript
const createFoo = (f) => f(/* ? */)
```

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

### Build TypeScript project

Source: https://zustand.docs.pmnd.rs/learn/guides/ssr-and-hydration.html

Compile TypeScript files using the project's tsconfig.json.

```bash
tsc --build
```

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

### onHydrate

Source: https://zustand.docs.pmnd.rs/reference/integrations/persisting-store-data.html

Registers a listener that is called when the hydration process starts. Returns an unsubscribe function to remove the listener.

```APIDOC
## onHydrate

### Description
Registers a listener that is called when the hydration process starts. Returns an unsubscribe function to remove the listener.

### Method
`onHydrate`

### Endpoint
`useBoundStore.persist.onHydrate(listener)`

### Parameters
- **listener** (function) - Required - A function that receives the state and is called when hydration starts.

### Response
- **function** - An unsubscribe function to remove the listener.

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

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

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

### Create a typed Zustand store with state and actions using create<BearState>()

Source: https://zustand.docs.pmnd.rs/learn/guides/beginner-typescript.html

Defines a BearState interface and uses the curried create<BearState>() form to enforce type safety. The store includes bears, food, and a feed action.

```typescript
// store.ts
import { create } from 'zustand'

// Define types for state & actions
interface BearState {
  bears: number
  food: string
  feed: (food: string) => void
}

// Create store using the curried form of `create`
export const useBearStore = create<BearState>()((set) => ({
  bears: 2,
  food: 'honey',
  feed: (food) => set(() => ({ food })),
}))
```
Tokens:
Raw