use-travel

React hooks for Travels: patch-based undo/redo state with immutable updates, manual archiving, rebasing, and shared-store support.

use-travel is the React layer for travels. It keeps the same core model as Travels, which stores JSON Patch history instead of full state snapshots, but exposes that model through React-friendly hooks:

• useTravel for component-scoped state with undo/redo
• useTravelStore for subscribing React components to an existing immutable Travels instance

Use plain travels directly when your state lives outside React, you need imperative reads right after navigation, or you need mutable: true.

Table of Contents

• Why use-travel?
• Installation
• Quick Start
• Choosing Between useTravel, useTravelStore, and travels
• API Reference
  • useTravel(initialState, options?)
  • useTravelStore(travels)
• Archive Modes
• Important Behavior
• Rebase
• Persistence
• State Requirements
• Examples
• Related Projects
• License

Why use-travel?

• React-first API: Use a hook tuple instead of wiring subscriptions manually.
• Patch-based history: Undo/redo stores only changes, not full state snapshots.
• Mutative update syntax: Write draft.count += 1 while keeping immutable React state.
• Manual archive mode: Group several edits into one undo step when needed.
• Rebase support: Promote the current state to the new reset baseline.
• Shared history support: Subscribe multiple React components to the same immutable Travels store with useTravelStore.

Installation

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

Version compatibility

| use-travel | travels | | ---------- | ------------------------------------------ | | >= 1.8.0 | >= 1.2.0 (required for rebase support) | | < 1.8.0 | < 1.2.0 |

Quick Start

import { useTravel } from 'use-travel';

export function Counter() {
  const [state, setState, controls] = useTravel({ count: 0 });

  return (
    <div>
      <strong>{state.count}</strong>

      <button
        onClick={() =>
          setState((draft) => {
            draft.count += 1;
          })
        }
      >
        Increment
      </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>
    </div>
  );
}

setState supports three update styles:

• Direct value: setState({ count: 1 })
• Function returning a value: setState(() => ({ count: 1 }))
• Draft mutation: setState((draft) => { draft.count += 1 })

Choosing Between useTravel, useTravelStore, and travels

• Use useTravel when the state belongs to a React component and React should own the lifecycle.
• Use useTravelStore when you already have a shared immutable Travels instance and want React to stay subscribed to it.
• Use plain travels when another layer is the source of truth, you need imperative getState() reads after back() or forward(), or you need mutable: true.

API Reference

useTravel(initialState, options?)

Creates a component-scoped immutable Travels instance and returns a tuple:

const [state, setState, controls] = useTravel(initialState, options);

useTravel always uses immutable mode internally so React can observe state changes through reference updates. mutable is intentionally not supported here.

Options

| Option | Type | Description | Default | | ---------------------- | ---------------- | --------------------------------------------------------------------------------- | ------------------------------------- | | maxHistory | number | Maximum number of history entries to keep | 10 | | initialPatches | TravelPatches | Patch history to restore from persistence | { patches: [], inversePatches: [] } | | strictInitialPatches | boolean | Throw when persisted patches are invalid instead of falling back to empty history | false | | initialPosition | number | History position to restore from persistence | 0 | | autoArchive | boolean | Save each change automatically or require manual archive() | true | | enableAutoFreeze | boolean | Forwarded to Mutative immutability options | false | | strict | boolean | Forwarded to Mutative strict immutability checks | false | | mark | Mark<O, F>[] | Forwarded to Mutative mark options | () => void | | patchesOptions | PatchesOptions | Customize patch output such as { pathAsArray: true } | enabled |

Returns

Common tuple members:

| Member | Type | Description | | --------------------------- | ---------------------------- | --------------------------------------------------------------------------- | | state | Value<S, F> | Current render snapshot | | setState | Updater<S> | Updates state with a value, function, or draft mutation | | controls.position | number | Current position in the history timeline | | controls.getHistory() | () => Value<S, F>[] | Returns the history as state snapshots | | controls.patches | TravelPatches | Returns the stored patch history | | controls.back(amount?) | (amount?: number) => void | Undo one or more steps | | controls.forward(amount?) | (amount?: number) => void | Redo one or more steps | | controls.go(position) | (position: number) => void | Jump to a specific history position | | controls.reset() | () => void | Reset to the initial state and clear history | | controls.rebase() | () => void | Make the current state the new baseline and discard past and future history | | controls.canBack() | () => boolean | Whether undo is possible | | controls.canForward() | () => boolean | Whether redo is possible |

When autoArchive: false, the controls also include:

| Member | Type | Description | | ----------------------- | --------------- | ------------------------------------------------------ | | controls.archive() | () => void | Commit the current working state as the next undo step | | controls.canArchive() | () => boolean | Whether there are unarchived changes |

useTravelStore(travels)

Subscribes React to an existing immutable Travels instance without creating a new store.

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

export const travels = new Travels({ count: 0 });

// 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>
  );
}

Important notes for useTravelStore:

• It only supports immutable Travels instances. Passing a store created with mutable: true throws.
• It exposes the same navigation controls as useTravel, including rebase().
• It is a React bridge, so the returned state is still a render snapshot.
• If you need imperative "navigate and read immediately" behavior, call travels.back() or travels.forward() and read travels.getState() directly from the store.

Archive Modes

use-travel supports two recording modes.

Auto Archive Mode

With the default autoArchive: true, every setState call becomes its own undo step.

const [state, setState, controls] = useTravel({ count: 0 });

function increment() {
  setState((draft) => {
    draft.count += 1;
  });
}

// Three separate user interactions:
// click #1 -> count = 1
// click #2 -> count = 2
// click #3 -> count = 3

controls.back(); // { count: 2 }

Manual Archive Mode

With autoArchive: false, you decide when the current working state should become a committed history entry.

This is useful for flows like forms, drag interactions, or multi-step editors where several changes should undo together.

const [doc, setDoc, controls] = useTravel(
  { title: '', body: '' },
  { autoArchive: false }
);

function onTitleChange(title: string) {
  setDoc((draft) => {
    draft.title = title;
  });
}

function onBodyChange(body: string) {
  setDoc((draft) => {
    draft.body = body;
  });
}

function save() {
  if (controls.canArchive()) {
    controls.archive();
  }
}

Important Behavior

One setState call per synchronous call stack

useTravel throws if setState is called more than once within the same synchronous call stack. If multiple fields need to change together, update them in a single draft mutation.

setState((draft) => {
  draft.count += 1;
  draft.todos.push({ id: 1, text: 'Buy milk' });
});

In manual archive mode, you can still make one setState call per event or render and archive later when the grouped change is ready.

initialState and options are read once

useTravel creates the underlying Travels instance only on the first render. Later changes to initialState or options do not recreate the history store automatically. If you need a fresh store, remount the component or change its key.

No-op updates are ignored

Updates that do not produce actual changes do not create history entries.

Rebase

controls.rebase() discards all past and future history and makes the current state the new baseline.

This is a destructive operation. After rebasing:

• controls.position becomes 0
• controls.getHistory() contains only the current state
• controls.reset() returns to the rebased state, not the original initial state
• In manual archive mode, any unarchived working changes become part of the new baseline

const [state, setState, controls] = useTravel({ count: 0 });

setState((draft) => {
  draft.count = 5;
});

controls.rebase();

setState((draft) => {
  draft.count = 9;
});

controls.reset(); // { count: 5 }

Persistence

use-travel re-exports TravelPatches, so you can persist both the current state and its history:

import type { TravelPatches } from 'use-travel';

type SavedTravel = {
  state: { count: number };
  patches: TravelPatches;
  position: number;
};

const saved: SavedTravel = {
  state,
  patches: controls.patches,
  position: controls.position,
};

Restore that data by passing the saved state as initialState and the saved history as initialPatches plus initialPosition:

const [state, setState, controls] = useTravel(saved.state, {
  initialPatches: saved.patches,
  initialPosition: saved.position,
});

If persisted patch data may be corrupt, set strictInitialPatches: true to fail fast instead of silently starting with empty history.

State Requirements

use-travel follows the same state rules as travels:

• Prefer plain JSON-serializable data.
• Map and Set are supported in immutable mode.
• Avoid complex mutable objects such as class instances, functions, DOM nodes, or framework-specific reactive proxies.

If you need mutable observable state, use travels directly instead of useTravelStore.

Examples

• Basic
• Manual Time Travel

Related Projects

• travels - The framework-agnostic undo/redo core
• zustand-travel - Zustand middleware built on Travels

License

use-travel is MIT licensed.