use-track-history

A lightweight React hook for state history tracking with undo/redo capabilities.

• 🪶 Lightweight: < 1KB minzipped, zero dependencies
• 🧠 Type-safe: Written in TypeScript with full type support
• 🧩 Flexible: Works with any data type (strings, objects, arrays)
• ⚡ Optimized: Uses React's built-in performance optimization hooks

Installation

npm install use-track-history # or: yarn add use-track-history

Quick Start

import { useTrackHistory } from "use-track-history";

function TextEditor() {
  const { value, update, reset, history } = useTrackHistory("Initial text");

  return (
    <div>
      <textarea value={value} onChange={(e) => update(e.target.value)} />

      <div className="toolbar">
        <button onClick={history.undo} disabled={!history.canUndo}>
          Undo
        </button>

        <button onClick={history.redo} disabled={!history.canRedo}>
          Redo
        </button>

        <button onClick={() => reset("Initial text")}>Reset</button>
      </div>
    </div>
  );
}

API Reference

useTrackHistory(defaultValue?, options?)

Creates a history-tracked state.

Parameters

| Parameter | Description | | -------------- | --------------------------------- | | defaultValue | Initial value to store in history | | options | Optional configuration object |

Options

| Option | Type | Description | | ---------------- | ------ | ------------------------------------------------------------------------------------- | | maxHistorySize | number | Maximum number of history entries to keep. When exceeded, oldest entries are removed. |

Return Object

| Property | Description | | --------- | ------------------------------------------------- | | value | Current value in the history | | update | Updates the value and adds it to history | | reset | Clears history and sets a new initial value | | history | Contains history control functions and properties |

History Object

| Property | Type | Description | | --------- | -------- | ------------------------------- | | undo | function | Move back to previous state | | redo | function | Move forward to next state | | canUndo | boolean | Check if undo is available | | canRedo | boolean | Check if redo is available | | length | number | Total number of history entries |

Common patterns

Using typed state

In Typescript, we can type our history object:

import { useTrackHistory } from "use-track-history";

type Profile = {
  name: string;
  age: number;
};

function MyComponent() {
  const { value, update, history } = useTrackHistory<Profile>({
    name: "Bob",
    age: 32,
  });

  // ...
}

Adding keyboard shortcuts

You can use the excellent react-hotkeys-hook library to add Cmd+Z and Cmd+Shift+Z keyboard shortcuts:

import { useTrackHistory } from "use-track-history";

function MyComponent() {
  const { value, update, history } = useTrackHistory("initial value");

  useHotkeys("mod+z", history.undo, {
    enabled: history.canUndo,
    preventDefault: true,
  });

  useHotkeys("mod+shift+z", history.redo, {
    // or ctrl+y on Windows
    enabled: history.canRedo,
    preventDefault: true,
  });

  // ...
}

Maximum history size

To limit memory usage, you might want to limit the history size:

import { useTrackHistory } from "use-track-history";

function MyComponent() {
  const { value, update, reset, history } = useTrackHistory("", {
    maxHistorySize: 30,
  });

  // ...
}