Every state change is a move. Take any of them back.

Installation

Install the package from npm. It needs React 18.2 or later, including React 19.

npm i @anandarizki/use-undo-redo

Using another package manager? pnpm add @anandarizki/use-undo-redo or yarn add @anandarizki/use-undo-redo work the same way.

Usage

Pass the hook the pair that useState gives you. It watches the value, records each change, and hands back undo and redo.

// import the hook
import { useUndoRedo } from "@anandarizki/use-undo-redo";

// your state handler
const [state, setState] = useState();

// pass your state and setState as the argument
const [undo, redo] = useUndoRedo([state, setState]);

Integrating into an existing component

You don’t need to change how your component manages state. Start with an ordinary counter:

import { useState } from "react";

function MyComponent() {
  const [count, setCount] = useState(0);

  return (
    <div>
      <button onClick={() => setCount(count - 1)}>-</button>
      {count}
      <button onClick={() => setCount(count + 1)}>+</button>
    </div>
  );
}

Add one line, then wire undo and redo to buttons. The counter’s own code stays exactly as it was.

import { useState } from "react";
import { useUndoRedo } from "@anandarizki/use-undo-redo";

function MyComponent() {
  const [count, setCount] = useState(0);

  // the new line
  const [undo, redo] = useUndoRedo([count, setCount]);

  return (
    <div>
      <button onClick={() => setCount(count - 1)}>-</button>
      {count}
      <button onClick={() => setCount(count + 1)}>+</button>

      <button onClick={undo}>Undo</button>
      <button onClick={redo}>Redo</button>
    </div>
  );
}

How history works

The hook keeps a list of entries and a pointer to the one you are on. Four rules cover everything it does; the board at the top of the page follows the same rules.

1. 1.

   Every change is recorded

   setCount(1); setCount(2); setCount(3)
   0

   1

   2

   3

   The first render stores the starting value. Each change after that is added to history, and pointer follows the newest entry.

2. 2.

   Undo moves the pointer

   undo(); undo()
   0

   1

   2

   3

   Nothing is deleted. The pointer steps back and your state is set to that entry. Entries ahead of the pointer are what redo can restore.

3. 3.

   A new change drops the redo branch

   setCount(5)
   0

   1

   2

   3

   5

   Changing state while you are behind the newest entry discards everything ahead of the pointer, like playing a different move after a takeback.

4. 4.

   Capacity trims the oldest

   setCount(6) // with { capacity: 3 }
   0

   1

   5

   6

   capacity counts every entry, including the starting one, so capacity: 3 allows two undo steps. When history is full, the oldest entry falls off.

5. pointer undo-able redo-able dropped

useUndoRedo

useUndoRedo<T>(
  primaryState: [T, (v: T) => void],
  options?: Options<T>
): Output<T>

primaryState is the [value, setValue] pair whose history the hook manages. Everything else is optional. Here is the full form:

const [undo, redo, { canUndo, canRedo, jumpTo, history, pointer, reset }] =
  useUndoRedo([state, setState], {
    debounce: 500,
    capacity: 20,
  });

Options

Returns

An array: [undo, redo, controls].

import type { Options, Output, StateHistory } from "@anandarizki/use-undo-redo";

type StateHistory<T> = {
  value: T;
  timestamp: Date;
};

Notes

• Changes are compared deeply with lodash isEqual. Setting a new object with the same content as the current entry is not recorded as a change.
• The functions are stable. undo, redo, jumpTo and reset keep the same identity across renders, so they are safe to pass to memoized components or list as effect dependencies.
• Store plain data. Class instances with private (#field) properties can’t be compared or cloned by lodash.

Recipes

Keyboard shortcuts

Because undo and redo are stable, you can bind them to Ctrl/⌘ Z once without re-subscribing on every render.

useEffect(() => {
  const onKeyDown = (e: KeyboardEvent) => {
    if (!(e.metaKey || e.ctrlKey) || e.key.toLowerCase() !== "z") return;
    e.preventDefault();
    if (e.shiftKey) redo();
    else undo();
  };
  window.addEventListener("keydown", onKeyDown);
  return () => window.removeEventListener("keydown", onKeyDown);
}, [undo, redo]);

Cloning strategies

The default deep clone is the safe choice. If you always update state immutably, or your values are large, choose how history copies them.

// Immutable updates only: store values as-is
useUndoRedo([todos, setTodos], { clone: false });

// Bring your own copy
useUndoRedo([doc, setDoc], { clone: (value) => structuredClone(value) });

// Keep every change
useUndoRedo([drawing, setDrawing], { capacity: Infinity });

Examples

The examples use shadcn/ui components for demonstration only. The hook doesn’t depend on any UI library.

UndoRedo button

Basic

Disabled buttons

Debounce

History list