Track hydration readiness
Show a loading indicator until persisted state is available.
Zustand · Pipe
onRehydrateStorage
onRehydrateStorage lets a persisted Zustand store run logic when storage hydration starts and optionally when it finishes. The completion callback receives the hydrated state and any hydration error.
How it works
onRehydrateStorage is a persist option for observing storage hydration. Its outer callback runs before hydration and may return a second callback that receives the resulting state and an optional error when hydration completes.
Syntax
onRehydrateStorage: (state: Object) => ((state?: Object, error?: Error) => void) | voidParameters
| Name | Type | Description |
|---|---|---|
state | Object | The store state available to the outer hydration listener. |
state | Object | undefined | The resulting state supplied to the returned callback after hydration; optional. |
error | Error | undefined | An optional hydration error supplied to the returned callback. |
Returns
The outer listener may return a callback (state?: Object, error?: Error) => void, or void; the returned callback runs after hydration.
Key points
- The option accepts a function receiving state; it may return a completion callback or return nothing.
- The listener is invoked as part of storage hydration.
- Code placed directly in the outer callback runs at the beginning of hydration.
- Returning a function creates a post-hydration hook with state and error inputs.
- The successful branch can perform actions after hydration has completed.
Common mistakes
- The listener concerns storage hydration, not every store update; use it specifically for pre- and post-hydration logic.
- If hydration is manually triggered, coordinate any loading or completion behavior with the listener and the explicit rehydrate call.
Example: Observe persistence hydration
import { create } from 'zustand'
import { persist } from 'zustand/middleware'
type State = {
ready: boolean
setReady: (ready: boolean) => void
}
export const useStore = create<State>()(
persist(
(set) => ({
ready: false,
setReady: (ready) => set({ ready }),
}),
{
name: 'app-state',
onRehydrateStorage: () => {
console.log('hydration starts')
return (state, error) => {
if (error) console.error('hydration failed', error)
else state?.setReady(true)
}
},
},
),
)The callback runs when hydration begins, and its returned callback runs afterward with the rehydrated state or an error.
When to use it
Monitor storage outcomes
Record successful hydration or report persistence failures.
Finalize restored state
Initialize or update a field after persisted values load.
Interview questions
QWhat does onRehydrateStorage do?
It is a persist option whose outer function receives the current state and can return another function. The returned function runs after hydration and receives the resulting state plus an optional error.
Follow-up: How would you detect failed hydration? Inspect the second callback’s error argument; a truthy value indicates that hydration encountered an error.
QWhy can the option return a function?
The outer callback is suitable for work that should happen when hydration starts. Returning a callback lets the store react when hydration finishes, whether successfully or with an error.
Follow-up: How can startup state reflect completion? Update a dedicated field in the returned callback after checking the error argument.
QHow can rehydration be triggered manually?
The option observes persistence hydration, while the store’s persisted data is loaded from storage. Rehydration can also be initiated explicitly through the store’s persist.rehydrate() method.
Follow-up: When might explicit rehydration matter? It is useful when hydration should be controlled manually rather than performed automatically during initialization.
Related
persistrehydrateskipHydrationstorage