URL-backed state
Persist state in a URL hash or query string.
Zustand · Type Alias
StateStorage
StateStorage is Zustand persist’s adapter type for custom persistence backends. Implement it when state should be stored somewhere other than the default localStorage-based setup.
How it works
StateStorage describes the storage adapter used by persist: an object supplying methods to read, write, and remove a named value. It can wrap browser storage or a custom backend; the documentation demonstrates URL-hash and URL-query implementations, while recommending createJSONStorage for a compliant adapter.
Syntax
type StateStorage = {
getItem: (name: string) => string | null | Promise<string | null>
setItem: (name: string, value: string) => void | Promise<void>
removeItem: (name: string) => void | Promise<void>
}Parameters
| Name | Type | Description |
|---|---|---|
storage | () => StateStorage | A storage factory supplied to persist; it returns the adapter used for persistence. |
Returns
A storage-adapter type used by persist; the page describes it as the return type of the storage option.
Key points
- Import the type from
zustand/middlewarewhen annotating a custom storage adapter. - The adapter lets persist target a backend other than the built-in browser storage.
- Configure persist with a storage factory that returns the adapter.
- A custom adapter may combine multiple backends, such as checking URL parameters before falling back to localStorage.
Common mistakes
- Prefer createJSONStorage when adapting a custom StateStorage object, so serialization and persist integration are handled consistently.
Example: Custom hash storage
import { createJSONStorage, persist, StateStorage } from 'zustand/middleware'
const hashStorage: StateStorage = {
getItem: (key) => new URLSearchParams(location.hash.slice(1)).get(key),
setItem: (key, value) => {
const params = new URLSearchParams(location.hash.slice(1))
params.set(key, value)
location.hash = params.toString()
},
removeItem: (key) => {
const params = new URLSearchParams(location.hash.slice(1))
params.delete(key)
location.hash = params.toString()
},
}
const storage = createJSONStorage(() => hashStorage)
void persist(() => ({ count: 0 }), { name: 'counter', storage })Implements a hash-backed storage adapter and converts it into persist-compatible JSON storage.
When to use it
Alternative storage engines
Use browser or mobile storage with persist.
Fallback persistence
Choose between URL parameters and localStorage.
Interview questions
QWhat problem does StateStorage solve?
StateStorage is the adapter shape consumed by persist for storing serialized state. It lets the middleware use a custom backend instead of its default localStorage-based storage.
Follow-up: How would you adapt an asynchronous backend? Use an async-compatible storage implementation and account for the cost of asynchronous persistence during rehydration and writes.
QHow do you create a custom StateStorage adapter?
Import StateStorage from zustand/middleware and implement the storage methods against the chosen backend. The documentation shows this pattern for URL hashes and query parameters.
Follow-up: How can JSON serialization be added without duplicating parsing logic? Pass the adapter through createJSONStorage and provide that result to persist.
QHow is StateStorage supplied to persist?
The persist option named storage is a function returning StateStorage, and its documented default is createJSONStorage(() => localStorage). A custom adapter replaces that default.
Follow-up: Why is the option a function rather than a storage object? A factory permits deferred access to browser-only storage and supports constructing the backend when needed.
Related
persistcreateJSONStoragelocalStorageAsyncStorage