use-travel

A React hook for state time travel with undo, redo, reset and archive functionalities with Travels.

Motivation

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.

Installation

npm install use-travel mutative travels
# or
yarn add use-travel mutative travels
# or
pnpm add use-travel mutative travels

Features

• 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

Example

• Basic
• Manual Time Travel

API

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().

import { useTravel } from 'use-travel';

const App = () => {
  const [state, setState, controls] = useTravel(0, {
    maxHistory: 10,
    initialPatches: {
      patches: [],
      inversePatches: [],
    },
  });
  return (
    <div>
      <div>{state}</div>
      <button onClick={() => setState(state + 1)}>Increment</button>
      <button onClick={() => setState(state - 1)}>Decrement</button>
      <button onClick={() => controls.back()} disabled={!controls.canBack()}>
        Undo
      </button>
      <button
        onClick={() => controls.forward()}
        disabled={!controls.canForward()}
      >
        Redo
      </button>
      <button onClick={controls.reset}>Reset</button>
      {controls.getHistory().map((state, index) => (
        <div key={index}>{state}</div>
      ))}
      {controls.patches.patches.map((patch, index) => (
        <div key={index}>{JSON.stringify(patch)}</div>
      ))}
      <div>{controls.position}</div>
      <button
        onClick={() => {
          controls.go(1);
        }}
      >
        Go
      </button>
    </div>
  );
};

Parameters

| Parameter | type | description | default | | ------------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | | maxHistory | 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<O, F>[] | 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) |

Returns

| Return | type | description | | --------------------- | ------------------------------ | ---------------------------------------------------------------------- | | state | Value<S, F> | The current state | | setState | Updater<InitialValue> | 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) |

useTravelStore

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.

// store.ts
import { Travels } from 'travels';

export const travels = new Travels({ count: 0 }); // mutable: true is not supported

// Counter.tsx
import { useTravelStore } from 'use-travel';
import { travels } from './store';

export function Counter() {
  const [state, setState, controls] = useTravelStore(travels);

  return (
    <div>
      <span>{state.count}</span>
      <button
        onClick={() =>
          setState((draft) => {
            draft.count += 1;
          })
        }
      >
        Increment
      </button>
      <button onClick={() => controls.back()} disabled={!controls.canBack()}>
        Undo
      </button>
    </div>
  );
}

useTravelStore 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.

Archive Mode

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.

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 (autoArchive: false)

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

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

function handleSave() {
  setState((draft) => {
    draft.count += 1;
  });
  controls.archive(); // Commit immediately
}

The key difference:

• Auto archive: Each setState = one undo step
• Manual archive: archive() call = one undo step (can include multiple setState calls)

Important Notes

⚠️ 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.

const App = () => {
  const [state, setState, controls] = useTravel({ count: 0, todo: [] });
  return (
    <div>
      <div>{state.count}</div>
      <button
        onClick={() => {
          // ❌ 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
      </button>
    </div>
  );
};

Note: With autoArchive: false, you can call setState once per event handler across multiple renders, then call archive() whenever you want to commit those changes to history.

Persistence

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:

const [state, setState, controls] = useTravel(initialState, {
  initialPatches,
  initialPosition,
});

License

use-travel is MIT licensed.