False
        

    Skip to content

      Navigation Menu

            Sign in Appearance settings
                * Platform
                        + AI CODE CREATION
                            o GitHub Copilot Write better code with AI
                            o GitHub Copilot app Direct agents from issue to merge
                            o MCP Registry Integrate external tools
                        + DEVELOPER WORKFLOWS
                            o Actions Automate any workflow
                            o Codespaces Instant dev environments
                            o Issues Plan and track work
                            o Code Review Manage code changes
                            o Code Quality Enforce quality at merge
                        + APPLICATION SECURITY
                            o GitHub Advanced Security Find and fix vulnerabilities
                            o Code security Secure your code as you build
                            o Secret protection Stop leaks before they start
                        + EXPLORE
                            o Why GitHub
                            o Documentation
                            o Blog
                            o Changelog
                            o Marketplace
                      View all features
                * Solutions
                        + BY COMPANY SIZE
                            o Enterprises
                            o Small and medium teams
                            o Startups
                            o Nonprofits
                        + BY USE CASE
                            o App Modernization
                            o DevSecOps
                            o DevOps
                            o CI/CD
                            o View all use cases
                        + BY INDUSTRY
                            o Healthcare
                            o Financial services
                            o Manufacturing
                            o Government
                            o View all industries
                      View all solutions
                * Resources
                        + EXPLORE BY TOPIC
                            o AI
                            o Software Development
                            o DevOps
                            o Security
                            o View all topics
                        + EXPLORE BY TYPE
                            o Customer stories
                            o Events & webinars
                            o Ebooks & reports
                            o Business insights
                            o GitHub Skills
                        + SUPPORT & SERVICES
                            o Documentation
                            o Customer support
                            o Community forum
                            o Trust center
                            o Partners
                      View all resources
                * Open Source
                        + COMMUNITY
                            o GitHub Sponsors Fund open source developers
                        + PROGRAMS
                            o Security Lab
                            o Maintainer Community
                            o Accelerator
                            o GitHub Stars
                            o Archive Program
                        + REPOSITORIES
                            o Topics
                            o Trending
                            o Collections
                * Enterprise
                        + ENTERPRISE SOLUTIONS
                            o Enterprise platform AI-powered developer platform
                        + AVAILABLE ADD-ONS
                            o GitHub Advanced Security Enterprise-grade security features
                            o Copilot for Business Enterprise-grade AI features
                            o Premium Support Enterprise-grade 24/7 support
              * Pricing
                Type / to search
                Sign in
              Sign up Appearance settings
      You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert

              Uh oh!

              There was an error while loading. Please reload this page.

              pmndrs / zustand Public

                      * Uh oh!

                        There was an error while loading. Please reload this page.

              * Notifications You must be signed in to change notification settings
              * Fork 2.2k
                * Star 58.5k
          * Code
          * Issues 2
          * Pull requests 3
          * Pull requests 4
          * Discussions
          * Actions
          * Projects
          * Wiki
          * Security and quality 0
          * Insights
          Additional navigation options
                  * Code
                  * Issues
                  * Pull requests
                  * Discussions
                  * Actions
                  * Projects
                  * Wiki
                  * Security and quality
                  * Insights
                                              main
                                          Branches Tags
                                            Go to file
                                        Code
                                          Open more actions menu

                                        Folders and files

                                          Name                         Name                           Last commit message    Last commit date
                                            Latest commit

                                                History

                                                1,372 Commits
                                                  1,372 Commits
                                                  .github                      .github
                                                  docs                         docs
                                                  examples                     examples
                                                  src                          src
                                                  tests                        tests
                                                  .gitignore                   .gitignore
                                                  .prettierignore              .prettierignore
                                                  CONTRIBUTING.md              CONTRIBUTING.md
                                                  FUNDING.json                 FUNDING.json
                                                  LICENSE                      LICENSE
                                                  README.md                    README.md
                                                  eslint.config.mjs            eslint.config.mjs
                                                  package.json                 package.json
                                                  pnpm-lock.yaml               pnpm-lock.yaml
                                                  pnpm-workspace.yaml          pnpm-workspace.yaml
                                                  rollup.config.mjs            rollup.config.mjs
                                                  tsconfig.json                tsconfig.json
                                                  vitest.config.mts            vitest.config.mts
                                            View all files


                                              Repository files navigation

                                                *
                                                * README
                                                * Contributing
                                                * MIT license
                                                More items

                                              A small, fast and scalable bearbones state-management solution using simplified flux principles. Has a comfy API based on hooks, isn't boilerplatey or opinionated.

                                              Don't disregard it because it's cute. It has quite the claws, lots of time was spent dealing with common pitfalls, like the dreaded zombie child problem, react concurrency, and context loss between mixed renderers. It may be the one state-manager in the React space that gets all of these right.

                                              You can try a live demo and read the docs.

                                                npm install zustand

                                              ⚠️ This readme is written for JavaScript users. If you are a TypeScript user, be sure to check out our TypeScript Usage section.

                                                First create a store

                                              Your store is a hook! You can put anything in it: primitives, objects, functions. State has to be updated immutably and the set function merges state to help it.

                                                import { create } from 'zustand'

                                                const useBearStore = create((set) => ({
                                                  bears: 0,
                                                  increasePopulation: () => set((state) => ({ bears: state.bears + 1 })),
                                                  removeAllBears: () => set({ bears: 0 }),
                                                }))

                                                Then bind your components, and that's it!

                                              Use the hook anywhere, no providers are needed. Select your state and the component will re-render on changes.

                                                function BearCounter() {
                                                  const bears = useBearStore((state) => state.bears)
                                                  return <h1>{bears} around here ...</h1>
                                                }

                                                function Controls() {
                                                  const increasePopulation = useBearStore((state) => state.increasePopulation)
                                                  return <button onClick={increasePopulation}>one up</button>
                                                }

                                                Why zustand over redux?

                                                * Simple and un-opinionated
                                                * Makes hooks the primary means of consuming state
                                                * Doesn't wrap your app in context providers
                                                * Can inform components transiently (without causing render)

                                                Why zustand over context?

                                                * Less boilerplate
                                                * Renders components only on changes
                                                * Centralized, action-based state management

                                                Recipes

                                                Fetching everything

                                              You can, but bear in mind that it will cause the component to update on every state change!

                                                const state = useBearStore()

                                                Selecting multiple state slices

                                              It detects changes with strict-equality (old === new) by default, this is efficient for atomic state picks.

                                                const nuts = useBearStore((state) => state.nuts)
                                                const honey = useBearStore((state) => state.honey)

                                              If you want to construct a single object with multiple state-picks inside, similar to redux's mapStateToProps, you can use useShallow to prevent unnecessary rerenders when the selector output does not change according to shallow equal.

                                                import { create } from 'zustand'
                                                import { useShallow } from 'zustand/react/shallow'

                                                const useBearStore = create((set) => ({
                                                  nuts: 0,
                                                  honey: 0,
                                                  treats: {},
                                                  // ...
                                                }))

                                                // Object pick, re-renders the component when either state.nuts or state.honey change
                                                const { nuts, honey } = useBearStore(
                                                  useShallow((state) => ({ nuts: state.nuts, honey: state.honey })),
                                                )

                                                // Array pick, re-renders the component when either state.nuts or state.honey change
                                                const [nuts, honey] = useBearStore(
                                                  useShallow((state) => [state.nuts, state.honey]),
                                                )

                                                // Mapped picks, re-renders the component when state.treats changes in order, count or keys
                                                const treats = useBearStore(useShallow((state) => Object.keys(state.treats)))

                                              For more control over re-rendering, you may provide any custom equality function (this example requires the use of createWithEqualityFn).

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

                                                Overwriting state

                                              The set function has a second argument, false by default. Instead of merging, it will replace the state model. Be careful not to wipe out parts you rely on, like actions.

                                                const useFishStore = create((set) => ({
                                                  salmon: 1,
                                                  tuna: 2,
                                                  deleteEverything: () => set({}, true), // clears the entire store, actions included
                                                  deleteTuna: () => set(({ tuna, ...rest }) => rest, true),
                                                }))

                                                Async actions

                                              Just call set when you're ready, zustand doesn't care if your actions are async or not.

                                                const useFishStore = create((set) => ({
                                                  fishies: {},
                                                  fetch: async (pond) => {
                                                    const response = await fetch(pond)
                                                    set({ fishies: await response.json() })
                                                  },
                                                }))

                                                Read from state in actions

                                              set allows fn-updates set(state => result), but you still have access to state outside of it through get.

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

                                                Reading/writing state and reacting to changes outside of components

                                              Sometimes you need to access state in a non-reactive way or act upon the store. For these cases, the resulting hook has utility functions attached to its prototype.

                                              ⚠️ This technique is not recommended for adding state in React Server Components (typically in Next.js 13 and above). It can lead to unexpected bugs and privacy issues for your users. For more details, see #2200.

                                                const useDogStore = create(() => ({ paw: true, snout: true, fur: true }))

                                                // Getting non-reactive fresh state
                                                const paw = useDogStore.getState().paw
                                                // Listening to all changes, fires synchronously on every change
                                                const unsub1 = useDogStore.subscribe(console.log)
                                                // Updating state, will trigger listeners
                                                useDogStore.setState({ paw: false })
                                                // Unsubscribe listeners
                                                unsub1()

                                                // You can of course use the hook as you always would
                                                function Component() {
                                                  const paw = useDogStore((state) => state.paw)
                                                  ...

                                                Using subscribe with selector

                                              If you need to subscribe with a selector, subscribeWithSelector middleware will help.

                                              With this middleware subscribe accepts an additional signature:

                                                subscribe(selector, callback, options?: { equalityFn, fireImmediately }): Unsubscribe
                                                import { subscribeWithSelector } from 'zustand/middleware'
                                                const useDogStore = create(
                                                  subscribeWithSelector(() => ({ paw: true, snout: true, fur: true })),
                                                )

                                                // Listening to selected changes, in this case when "paw" changes
                                                const unsub2 = useDogStore.subscribe((state) => state.paw, console.log)
                                                // Subscribe also exposes the previous value
                                                const unsub3 = useDogStore.subscribe(
                                                  (state) => state.paw,
                                                  (paw, previousPaw) => console.log(paw, previousPaw),
                                                )
                                                // Subscribe also supports an optional equality function
                                                const unsub4 = useDogStore.subscribe(
                                                  (state) => [state.paw, state.fur],
                                                  console.log,
                                                  { equalityFn: shallow },
                                                )
                                                // Subscribe and fire immediately
                                                const unsub5 = useDogStore.subscribe((state) => state.paw, console.log, {
                                                  fireImmediately: true,
                                                })

                                                Using zustand without React

                                              Zustand core can be imported and used without the React dependency. The only difference is that the create function does not return a hook, but the API utilities.

                                                import { createStore } from 'zustand/vanilla'

                                                const store = createStore((set) => ...)
                                                const { getState, setState, subscribe, getInitialState } = store

                                                export default store

                                              You can use a vanilla store with useStore hook available since v4.

                                                import { useStore } from 'zustand'
                                                import { vanillaStore } from './vanillaStore'

                                                const useBoundStore = (selector) => useStore(vanillaStore, selector)

                                              ⚠️ Note that middlewares that modify set or get are not applied to getState and setState.

                                                Transient updates (for often occurring state-changes)

                                              The subscribe function allows components to bind to a state-portion without forcing re-render on changes. Best combine it with useEffect for automatic unsubscribe on unmount. This can make a drastic performance impact when you are allowed to mutate the view directly.

                                                const useScratchStore = create((set) => ({ scratches: 0, ... }))

                                                const Component = () => {
                                                  // Fetch initial state
                                                  const scratchRef = useRef(useScratchStore.getState().scratches)
                                                  // Connect to the store on mount, disconnect on unmount, catch state-changes in a reference
                                                  useEffect(() => useScratchStore.subscribe(
                                                    state => (scratchRef.current = state.scratches)
                                                  ), [])
                                                  ...

                                                Sick of reducers and changing nested states? Use Immer!

                                              Reducing nested structures is tiresome. Have you tried immer?

                                                import { produce } from 'immer'

                                                const useLushStore = create((set) => ({
                                                  lush: { forest: { contains: { a: 'bear' } } },
                                                  clearForest: () =>
                                                    set(
                                                      produce((state) => {
                                                        state.lush.forest.contains = null
                                                      }),
                                                    ),
                                                }))

                                                const clearForest = useLushStore((state) => state.clearForest)
                                                clearForest()

                                              Alternatively, there are some other solutions.

                                                Persist middleware

                                              You can persist your store's data using any kind of storage.

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

                                                const useFishStore = create(
                                                  persist(
                                                    (set, get) => ({
                                                      fishes: 0,
                                                      addAFish: () => set({ fishes: get().fishes + 1 }),
                                                    }),
                                                    {
                                                      name: 'food-storage', // name of the item in the storage (must be unique)
                                                      storage: createJSONStorage(() => sessionStorage), // (optional) by default, 'localStorage' is used
                                                    },
                                                  ),
                                                )

                                              See the full documentation for this middleware.

                                                Immer middleware

                                              Immer is available as middleware too.

                                                import { create } from 'zustand'
                                                import { immer } from 'zustand/middleware/immer'

                                                const useBeeStore = create(
                                                  immer((set) => ({
                                                    bees: 0,
                                                    addBees: (by) =>
                                                      set((state) => {
                                                        state.bees += by
                                                      }),
                                                  })),
                                                )

                                                Can't live without redux-like reducers and action types?

                                                const types = { increase: 'INCREASE', decrease: 'DECREASE' }

                                                const reducer = (state, { type, by = 1 }) => {
                                                  switch (type) {
                                                    case types.increase:
                                                      return { grumpiness: state.grumpiness + by }
                                                    case types.decrease:
                                                      return { grumpiness: state.grumpiness - by }
                                                  }
                                                }

                                                const useGrumpyStore = create((set) => ({
                                                  grumpiness: 0,
                                                  dispatch: (args) => set((state) => reducer(state, args)),
                                                }))

                                                const dispatch = useGrumpyStore((state) => state.dispatch)
                                                dispatch({ type: types.increase, by: 2 })

                                              Or, just use our redux-middleware. It wires up your main-reducer, sets the initial state, and adds a dispatch function to the state itself and the vanilla API.

                                                import { redux } from 'zustand/middleware'

                                                const useGrumpyStore = create(redux(reducer, initialState))

                                                Redux devtools

                                              Install the Redux DevTools Chrome extension to use the devtools middleware.

                                                import { devtools } from 'zustand/middleware'

                                                // Usage with a plain action store, it will log actions as "setState"
                                                const usePlainStore = create(devtools((set) => ...))
                                                // Usage with a redux store, it will log full action types
                                                const useReduxStore = create(devtools(redux(reducer, initialState)))

                                              One redux devtools connection for multiple stores

                                                import { devtools } from 'zustand/middleware'

                                                // Usage with a plain action store, it will log actions as "setState"
                                                const usePlainStore1 = create(devtools((set) => ..., { name, store: storeName1 }))
                                                const usePlainStore2 = create(devtools((set) => ..., { name, store: storeName2 }))
                                                // Usage with a redux store, it will log full action types
                                                const useReduxStore1 = create(devtools(redux(reducer, initialState)), { name, store: storeName3 })
                                                const useReduxStore2 = create(devtools(redux(reducer, initialState)), { name, store: storeName4 })

                                              Assigning different connection names will separate stores in redux devtools. This also helps group different stores into separate redux devtools connections.

                                              devtools takes the store function as its first argument, optionally you can name the store or configure serialize options with a second argument.

                                              Name store: devtools(..., {name: "MyStore"}), which will create a separate instance named "MyStore" in the devtools.

                                              Serialize options: devtools(..., { serialize: { options: true } }).

                                                Logging Actions

                                              devtools will only log actions from each separated store unlike in a typical combined reducers redux store. See an approach to combining stores #163

                                              You can log a specific action type for each set function by passing a third parameter:

                                                const useBearStore = create(devtools((set) => ({
                                                  ...
                                                  eatFish: () => set(
                                                    (prev) => ({ fishes: prev.fishes > 1 ? prev.fishes - 1 : 0 }),
                                                    undefined,
                                                    'bear/eatFish'
                                                  ),
                                                  ...

                                              You can also log the action's type along with its payload:

                                                  ...
                                                  addFishes: (count) => set(
                                                    (prev) => ({ fishes: prev.fishes + count }),
                                                    undefined,
                                                    { type: 'bear/addFishes', count, }
                                                  ),
                                                  ...

                                              If an action type is not provided, it is defaulted to "anonymous". You can customize this default value by providing an anonymousActionType parameter:

                                                devtools(..., { anonymousActionType: 'unknown', ... })

                                              If you wish to disable devtools (on production for instance). You can customize this setting by providing the enabled parameter:

                                                devtools(..., { enabled: false, ... })

                                                React context

                                              The store created with create doesn't require context providers. In some cases, you may want to use contexts for dependency injection or if you want to initialize your store with props from a component. Because the normal store is a hook, passing it as a normal context value may violate the rules of hooks.

                                              The recommended method available since v4 is to use the vanilla store.

                                                import { createContext, useContext } from 'react'
                                                import { createStore, useStore } from 'zustand'

                                                const store = createStore(...) // vanilla store without hooks

                                                const StoreContext = createContext()

                                                const App = () => (
                                                  <StoreContext.Provider value={store}>
                                                    ...
                                                  </StoreContext.Provider>
                                                )

                                                const Component = () => {
                                                  const store = useContext(StoreContext)
                                                  const slice = useStore(store, selector)
                                                  ...

                                                TypeScript Usage

                                              Basic typescript usage doesn't require anything special except for writing create<State>()(...) instead of create(...)...

                                                import { create } from 'zustand'
                                                import { devtools, persist } from 'zustand/middleware'
                                                import type {} from '@redux-devtools/extension' // required for devtools typing

                                                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: 'bear-storage',
                                                      },
                                                    ),
                                                  ),
                                                )

                                              A more detailed TypeScript guide is here and there.

                                                Best practices

                                                * You may wonder how to organize your code for better maintenance: Splitting the store into separate slices.
                                                * Recommended usage for this unopinionated library: Flux inspired practice.
                                                * Calling actions outside a React event handler in pre-React 18.
                                                * Testing
                                                * For more, have a look in the docs folder

                                                Third-Party Libraries

                                              Some users may want to extend Zustand's feature set which can be done using third-party libraries made by the community. For information regarding third-party libraries with Zustand, visit the doc.

                                                Comparison with other libraries

                                                * Difference between zustand and other state management libraries for React

                                        About

                                        🐻 Bear necessities for state management in React

                                          zustand-demo.pmnd.rs/

                                        Topics

                                          hacktoberfesthooksreactreact-contextreactjsreduxstate-management

                                        Resources

                                          Readme
                                          MIT license

                                        Contributing

                                          Contributing
                                          Activity
                                          Custom properties

                                        Stars

                                          58.5k stars

                                        Watchers

                                          203 watching

                                        Forks

                                          2.2k forks
                                          Report repository

                                        Releases

                                        Sponsor this project

                                        Packages

                                        Used by

                                        Contributors

                                        Languages

    Footer

        © 2026 GitHub, Inc.

      Footer navigation

        * Terms
        * Privacy
        * Security
        * Status
        * Community
        * Docs
        * Contact
        * Manage cookies
        * Do not share my personal information
      You can’t perform that action at this time.