Persist application state
A store must survive browser refreshes or application restarts.
Zustand · Type Alias
PersistOptions
PersistOptions configures storage, filtering, rehydration, and versioning for Zustand's persist middleware. The required name identifies the persisted store; other fields customize how state is saved and restored.
How it works
PersistOptions configures how the persist middleware stores and restores Zustand state. It requires a unique name and can customize storage, select persisted fields, handle rehydration, and control version compatibility or migration.
Syntax
persist<T, U = T>(stateCreatorFn: StateCreator<T, [], []>, persistOptions: PersistOptions<T, U>): StateCreator<T, [['zustand/persist', U]], []>Parameters
| Name | Type | Description |
|---|---|---|
stateCreatorFn | StateCreator<T, [], []> | Store state creator receiving set, get, and store; its result is the state and actions to expose. |
persistOptions | PersistOptions<T, U> | Persistence configuration. It includes required name and optional storage, partialize, onRehydrateStorage, version, and other documented persistence controls. |
name | string | Unique storage key for the persisted store; required. |
storage | PersistStorage<U> (optional) | Storage adapter for reading and writing persisted state. Defaults to JSON storage backed by localStorage. |
partialize | (state: T) => U (optional) | Selects the state subset written to storage. |
onRehydrateStorage | (state: T) => void | ((state?: T, error?: unknown) => void) (optional) | Runs custom logic before and after rehydration. |
version | number (optional) | Persisted-data version used to detect incompatible stored state. |
Returns
A StateCreator that adds the zustand/persist middleware mutator and persists the configured store state.
Key points
- PersistOptions is passed as the second argument to persist and is generic over the store state and persisted-state shape.
- The options object controls persistence behavior rather than defining store actions or selectors.
- The optional storage field accepts a custom PersistStorage implementation.
- The optional partialize callback determines which state fields are saved.
- onRehydrateStorage supports lifecycle logic around restoring persisted state.
- version labels the persisted representation so incompatible stored data can be detected.
Common mistakes
- Changing the version without supplying compatible migration behavior causes persisted data with another version to be ignored.
- Storage creation is deferred until first access, which helps avoid unavailable browser-storage APIs during server-side rendering.
Example: Persist selected store state
import { create } from 'zustand'
import { persist } from 'zustand/middleware'
type Settings = {
theme: 'light' | 'dark'
setTheme: (theme: Settings['theme']) => void
}
export const useSettings = create<Settings>()(
persist(
(set) => ({
theme: 'light',
setTheme: (theme) => set({ theme }),
}),
{
name: 'settings',
partialize: (state) => ({ theme: state.theme }),
version: 1,
},
),
)Creates a persisted Zustand store with a unique storage key, saves only the theme, and associates persisted data with version 1.
When to use it
Persist a selected subset
Only durable preferences should be saved while actions or transient data remain in memory.
Select custom storage
A store uses sessionStorage, IndexedDB, or another persistence adapter instead of localStorage.
Manage persisted-state versions
The serialized state shape changes between releases.
Interview questions
QWhich PersistOptions field is required, and what does it do?
name is the required persistence option and becomes the storage key for the Zustand state. It must be unique within the selected storage so different stores do not collide.
Follow-up: What happens when the stored version differs? The persisted value is not used unless the configuration handles the version transition, typically through migration.
QHow can PersistOptions change the storage backend?
storage supplies a PersistStorage implementation for reading and writing data. If omitted, persistence uses JSON storage backed by localStorage.
Follow-up: Why is the default storage wrapped? The JSON-storage helper provides serialization and lazily evaluates the storage getter, which is safer when browser APIs are unavailable at module evaluation.
QHow do you persist only selected state fields?
partialize receives the store state and returns the subset written to persistence. This lets an application exclude transient or sensitive fields from stored data.
Follow-up: How does this affect TypeScript middleware typing? The persisted-state type corresponds to the result of partialize; without it, the documentation describes it as a partial form of the full state.
Related
persistPersistStoragecreateJSONStorageStateCreatorrehydratemigrate