A React hook for state time travel with undo, redo, reset and archive functionalities.
npm install use-travel!Node CI
!license
A React hook for state time travel with undo, redo, reset and archive functionalities with Travels.
use-travel is a small and high-performance library for state time travel. It's built on Mutative and Travels to support mutation updating immutable data. It's designed to be simple and easy to use, and it's also customizable for different use cases.
It's suitable for building any time travel feature in your application.
``bash`
npm install use-travel mutative travelsor
yarn add use-travel mutative travelsor
pnpm add use-travel mutative travels
- Undo/Redo/Reset/Go/Archive functionalities
- Mutations update immutable data
- Small size for time travel with JSON Patch history
- Customizable history size
- Customizable initial patches
- High performance
- Mark function for custom immutability
You can use useTravel to create a time travel state. And it returns a tuple with the current state, the state setter, and the controls. The controls include back(), forward(), reset(), canBack(), canForward(), canArchive(), getHistory(), patches, position, archive(), and go().
`jsx
import { useTravel } from 'use-travel';
const App = () => {
const [state, setState, controls] = useTravel(0, {
maxHistory: 10,
initialPatches: {
patches: [],
inversePatches: [],
},
});
return (
$3
| Parameter | type | description | default |
| ------------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
|
| number | The maximum number of history to keep | 10 |
| initialPatches | TravelPatches | The initial patches | {patches: [],inversePatches: []} |
| initialPosition | number | The initial position of the state | 0 |
| autoArchive | boolean | Auto archive the state (see Archive Mode for details) | true |
| enableAutoFreeze | boolean | Enable auto freeze the state, view more | false |
| strict | boolean | Enable strict mode, view more | false |
| mark | Mark | The mark function , view more | () => void |
| patchesOptions | boolean ｜ PatchesOptions | Customize JSON Patch format. Supports { pathAsArray: boolean } to control path format. See Mutative patches docs | true (enable patches) |$3
| Return | type | description |
| --------------------- | ------------------------------ | ---------------------------------------------------------------------- |
|
state | Value | The current state |
| setState | Updater> | The state setter, support mutation update or return immutable data |
| controls.back | (amount?: number) => void | Go back to the previous state |
| controls.forward | (amount?: number) => void | Go forward to the next state |
| controls.reset | () => void | Reset the state to the initial state |
| controls.canBack | () => boolean | Check if can go back to the previous state |
| controls.canForward | () => boolean | Check if can go forward to the next state |
| controls.canArchive | () => boolean | Check if can archive the current state |
| controls.getHistory | () => T[] | Get the history of the state |
| controls.patches | TravelPatches[] | Get the patches history of the state |
| controls.position | number | Get the current position of the state |
| controls.go | (nextPosition: number) => void | Go to the specific position of the state |
| controls.archive | () => void | Archive the current state(the autoArchive options should be false) |$3
When you need to manage a single
Travels instance outside of React—e.g. to share the same undo/redo history across multiple components—create the store manually and bind it with useTravelStore. The hook keeps React in sync with the external store, exposes the same controls object, and rejects mutable stores to ensure React can observe updates.`tsx
// store.ts
import { Travels } from 'travels';export const travels = new Travels({ count: 0 }); // mutable: true is not supported
`tsx
// Counter.tsx
import { useTravelStore } from 'use-travel';
import { travels } from './store';export function Counter() {
const [state, setState, controls] = useTravelStore(travels);
return (
{state.count}
setState((draft) => {
draft.count += 1;
})
}
>
Increment
);
}
` stays reactive even when the Travels instance is updated elsewhere (for example, in services or other components) and forwards manual archive helpers when the store is created with autoArchive: false.$3
use-travel provides two archive modes to control how state changes are recorded in history:#### Auto Archive Mode (default:
autoArchive: true)In auto archive mode, every
setState call is automatically recorded as a separate history entry. This is the simplest mode and suitable for most use cases.`jsx
const [state, setState, controls] = useTravel({ count: 0 });
// or explicitly: useTravel({ count: 0 }, { autoArchive: true })// Each setState creates a new history entry
setState({ count: 1 }); // History: [0, 1]
// ... user clicks another button
setState({ count: 2 }); // History: [0, 1, 2]
// ... user clicks another button
setState({ count: 3 }); // History: [0, 1, 2, 3]
controls.back(); // Go back to count: 2
`#### Manual Archive Mode (
)In manual archive mode, you control when state changes are recorded to history using the
archive() function. This is useful when you want to group multiple state changes into a single undo/redo step.Use Case 1: Batch multiple changes into one history entry
`jsx
const [state, setState, controls] = useTravel(
{ count: 0 },
{
autoArchive: false,
}
);// Multiple setState calls across different renders
setState({ count: 1 }); // Temporary change (not in history yet)
// ... user clicks another button
setState({ count: 2 }); // Temporary change (not in history yet)
// ... user clicks another button
setState({ count: 3 }); // Temporary change (not in history yet)
// Commit all changes as a single history entry
controls.archive(); // History: [0, 3]
// Now undo will go back to 0, not 2 or 1
controls.back(); // Back to 0
`Use Case 2: Explicit commit after a single change
jsx
function handleSave() {
setState((draft) => {
draft.count += 1;
});
controls.archive(); // Commit immediately
}
`The key difference:
- Auto archive: Each
= one undo step
- Manual archive: archive() call = one undo step (can include multiple setState calls)$3
> ⚠️ setState Restriction:
setState can only be called once within the same synchronous call stack (e.g., inside a single event handler). This ensures predictable undo/redo behavior where each history entry represents a clear, atomic change.`jsx
const App = () => {
const [state, setState, controls] = useTravel({ count: 0, todo: [] });
return (
{state.count}
// ❌ Multiple setState calls in the same event handler
setState((draft) => {
draft.count += 1;
});
setState((draft) => {
draft.todo.push({ id: 1, text: 'Buy' });
});
// This will throw: "setState cannot be called multiple times in the same render cycle" // ✅ Correct: Batch all changes in a single setState
setState((draft) => {
draft.count += 1;
draft.todo.push({ id: 1, text: 'Buy' });
});
}}
>
Update
);
};
`> Note: With
, you can call setState once per event handler across multiple renders, then call archive() whenever you want to commit those changes to history.$3
>
TravelPatches is the type of patches history, it includes patches and inversePatches.> If you want to persist the state, you can use
state/controls.patches/controls.position to save the travel history. Then, read the persistent data as initialState, initialPatches, and initialPosition when initializing the state, like this:`jsx
const [state, setState, controls] = useTravel(initialState, {
initialPatches,
initialPosition,
});
`License