useReducerHistory

Custom useReducer that tracks and allows to use previous values.

Demo

INFO

The implementation is like that useStateHistory but built on useReducer.

Please visit useStateHistory example to see how it works.

Types

ReducerHistoryControls

• @template R - The reducer type.

The history controls object returned as part of {@link UseReducerHistoryResult} and {@link UseReducerHistoryGetterResult}.

Property	Type	Required	Description
history	readonly ReducerState<R>[]	✓	A read-only array of all recorded state snapshots, from oldest to most recent. The entry at presentPointer is the currently active state.
presentPointer	number	✓	The index within history that corresponds to the current state. Moves backward on undo and forward on redo or a new dispatch.
trackUpdate	(enable: boolean) => void	✓	Enables or disables history recording. When called with false, dispatched actions still update the state but are not added to history. Re-enable with true to resume recording.
canUndo	boolean	✓	true when there is at least one state snapshot before presentPointer that can be restored via undo.
canRedo	boolean	✓	true when there is at least one state snapshot after presentPointer that can be restored via redo.
undo	() => void	✓	Moves presentPointer one step backward in history and restores the corresponding state. No-op when canUndo is false.
redo	() => void	✓	Moves presentPointer one step forward in history and restores the corresponding state. No-op when canRedo is false.
go	(index: number) => void	✓	Jumps directly to the state at the given index in history, updating presentPointer and restoring that snapshot.
clear	(value?: ReducerAction<R>) => void	✓	Clears the entire history array. When value is provided, the cleared history is replaced with a single entry computed by dispatching value against the current state; otherwise the history is reset to the current state only.

UseReducerHistoryProps

• @template R - The reducer type, extending Reducer<any, any>.

Parameters accepted by useReducerHistory and useReducerHistoryGetter.

Property	Type	Required	Description
reducer	R	✓	The reducer function (state, action) => state that computes the next state given the current state and a dispatched action.
initialState	ReducerState<R>	✓	The initial reducer state value, passed directly to useReducer.
initializer	(init: ReducerState<R>) => ReducerState<R>		An optional initializer function that receives initialState and returns the actual initial state. Useful for lazily computing the initial value or extracting it from a larger object.
capacity	number \| "no-limit"		Maximum number of state snapshots retained in history: - "no-limit" (default) — All snapshots are retained indefinitely. - number — Once the limit is reached, the oldest snapshot is evicted to make room for the new one (FIFO).

UseReducerHistoryResult

• @template R - The reducer type.

Return value of useReducerHistory.

Index	Type	Description
[0]	ReducerState<R>	The current reducer state, reactive — triggers a re-render when updated.
[1]	Dispatch<ReducerAction<R>>	The stable dispatch function used to send actions to the reducer.
[2]	ReducerHistoryControls<R>	The history controls object. See {@link ReducerHistoryControls}.

UseReducerHistoryGetterResult

• @template R - The reducer type.

Return value of useReducerHistoryGetter.

Index	Type	Description
[0]	ReducerState<R>	The current reducer state, reactive — triggers a re-render when updated.
[1]	Dispatch<ReducerAction<R>>	The stable dispatch function used to send actions to the reducer.
[2]	() => ReducerState<R>	A stable getter that returns the current reducer state synchronously without causing a re-render. Useful for reading state inside callbacks without adding it as a dependency.
[3]	ReducerHistoryControls<R>	The history controls object. See {@link ReducerHistoryControls}.