> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superdoc.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Track changes

Word-style revision tracking. Every edit carries an author, a timestamp, and an id. Accept or reject one at a time, by selection, or in bulk. Changes round-trip through DOCX as native Word revisions: import, edit, export, nothing lost.

> [!TIP]
>
> Building your own review panel in React? Skip the built-in UI and read [Custom UI › Track changes](https://docs.superdoc.dev/editor/custom-ui/track-changes.md) instead. It documents `useSuperDocTrackChanges` plus accept / reject / next / previous and the typed surface for accept-all / reject-all flows.

## Quick start

```javascript theme={null}
const superdoc = new SuperDoc({
  selector: "#editor",
  document: "contract.docx",
  documentMode: "suggesting", // record new edits as tracked changes
  user: {
    name: "John Smith",
    email: "john@company.com",
  },
  modules: {
    trackChanges: {
      visible: true,
    },
  },
  onCommentsUpdate: (payload) => {
    if (payload.type === "trackedChange") {
      console.log(payload.event, payload.trackedChangeType, payload.changeId);
    }
  },
});
```

> [!NOTE]
>
> Tracked-edit recording follows `documentMode`. Set `documentMode: 'suggesting'` (or call `superdoc.setDocumentMode('suggesting')` later) to start recording new edits as revisions.

## Configuration

**modules.trackChanges.visible** `boolean` (default: false)

Show tracked-change markup when `documentMode` is `viewing`.

**modules.trackChanges.mode** `'review' | 'original' | 'final' | 'off'`

Rendering mode.

**Values**

* `'review'`: show insertions and deletions inline (default for editing and suggesting).
* `'original'`: show the document as it was before tracked changes (default for viewing when `visible` is `false`).
* `'final'`: show the document with all changes applied.
* `'off'`: suppress tracked-change rendering entirely.

**modules.trackChanges.enabled** `boolean` (default: true)

Whether the layout engine treats tracked changes as active. Turn off to render the document without any revision UI.

**modules.trackChanges.replacements** `'paired' | 'independent'` (default: 'paired')

How a tracked replacement (typing over selected text) surfaces in the API and UI. See [Revision model](#revision-model).

**Values**

* `'paired'` (default, Google Docs model): the insertion and deletion share one id and resolve together.
* `'independent'` (Microsoft Word / ECMA-376 §17.13.5): each side has its own id and resolves on its own.

**modules.trackChanges.authorColors** `Object`

Resolve one highlight color per tracked-change author. This replaces app-side CSS overrides like `[data-track-change-author]` selectors.

**Fields**

**modules.trackChanges.authorColors.enabled** `boolean` (default: true)

Set to `false` to keep the default insert, delete, and format colors.

**modules.trackChanges.authorColors.overrides** `Record\<string, string\>`

Exact color overrides keyed by author email or author name. Email matches first, then name.

**modules.trackChanges.authorColors.resolve** `(author) =\> string | undefined`

Callback for authors not covered by `overrides`. Receives `{ name, email, image }`. Return any CSS color string, or `undefined` to use SuperDoc's deterministic fallback color.

```javascript theme={null}
new SuperDoc({
  selector: "#editor",
  document: "contract.docx",
  modules: {
    trackChanges: {
      visible: true,
      authorColors: {
        overrides: {
          "alice@example.com": "#1f6feb",
          "Bob Reviewer": "#d1242f",
        },
        resolve: (author) => {
          if (author.email?.endsWith("@outside-counsel.com")) return "#8250df";
          return undefined; // SuperDoc assigns a stable fallback color
        },
      },
    },
  },
});
```

Per-author colors apply to insertion, deletion, and format-change highlights. SuperDoc derives lighter background variants from the same author color and exposes the resolved colors through the custom UI snapshot.

## Viewing mode visibility

Tracked-change markup is hidden by default when `documentMode` is `'viewing'`. Flip `modules.trackChanges.visible` to show it in read-only mode.

```javascript theme={null}
new SuperDoc({
  selector: "#viewer",
  document: "contract.docx",
  documentMode: "viewing",
  modules: {
    trackChanges: { visible: true },
  },
});
```

> [!NOTE]
>
> The top-level `trackChanges` key still works as a deprecated alias for `modules.trackChanges` and prints a one-time console warning.

## Revision model

SuperDoc supports two models for how a tracked replacement (an insertion paired with a deletion, created when a user types over selected text) shows up in the API and UI. Pick the one that matches the editor your users expect.

| Model | `modules.trackChanges.replacements` | Behavior |
| - | - | - |
| **Paired** (default: Google Docs) | `'paired'` | Both halves share one id. One accept/reject resolves both. One sidebar row per replacement. |
| **Independent** (Microsoft Word / ECMA-376 §17.13.5) | `'independent'` | Each insertion and each deletion has its own id. Accept/reject resolves one side at a time. A replacement produces two sidebar rows. |

Both modes round-trip cleanly through DOCX: the OOXML always emits one `<w:ins>` / `<w:del>` per mark. The difference is how the API surfaces the revisions at runtime.

### Paired (default)

```javascript theme={null}
const superdoc = new SuperDoc({
  selector: "#editor",
  document: yourFile,
  // default: modules.trackChanges.replacements === 'paired'
});
```

### Independent (Word-style)

```javascript theme={null}
const superdoc = new SuperDoc({
  selector: "#editor",
  document: yourFile,
  modules: {
    trackChanges: { replacements: "independent" },
  },
});
```

With `replacements: 'independent'`, `editor.doc.trackChanges.list()` returns one entry per revision and `decide({ id })` resolves exactly that one side. The other half of the replacement stays in the document, still addressable by its own id: useful when you're building a custom sidebar and want each revision as a separate row.

## Document API

Use the Document API to list, read, and resolve tracked changes. It's stable, typed, framework-agnostic, and works the same in the visual editor and headless mode.

```javascript theme={null}
const editor = superdoc.activeEditor;

// List every tracked change. In 'paired' mode a replacement is one entry;
// in 'independent' mode it's two (one insert, one delete).
const result = editor.doc.trackChanges.list();

for (const item of result.items) {
  console.log(item.id, item.type, item.author, item.excerpt);
}

// Fetch a single change by id.
const change = editor.doc.trackChanges.get({ id: result.items[0].id });

// Accept or reject by id.
editor.doc.trackChanges.decide({ decision: "accept", target: { id: change.id } });

// Accept or reject everything in the document.
editor.doc.trackChanges.decide({ decision: "accept", target: { scope: "all" } });
```

Every entry returned by `list()` and `get()` has this shape:

**TrackChangeInfo** `Object`

**Fields**

**id** `string`

SuperDoc's internal id for the revision. Stable across calls.

**address** `Object`

Entity address: `{ kind: 'entity', entityType: 'trackedChange', entityId: id }`.

**type** `'insert' | 'delete' | 'format'`

Revision kind. In `'paired'` mode a replacement reports as `'insert'` (both halves grouped). In `'independent'` mode the insertion and deletion are separate entries.

**author** `string`

Display name of the reviewer.

**authorEmail** `string`

Email of the reviewer.

**authorImage** `string`

Reviewer avatar URL, when provided.

**date** `string`

ISO timestamp of the revision.

**excerpt** `string`

The affected text.

**wordRevisionIds** `Object`

Original Word `w:id` values from the source DOCX, keyed by `insert` / `delete` / `format`. Useful for correlating SuperDoc revisions with upstream systems.

`list()` accepts an optional query with `limit`, `offset`, and `type` (`'insert' | 'delete' | 'format'`) for pagination and filtering. See the full reference:

* [`trackChanges.list`](https://docs.superdoc.dev/document-api/reference/track-changes/list)
* [`trackChanges.get`](https://docs.superdoc.dev/document-api/reference/track-changes/get)
* [`trackChanges.decide`](https://docs.superdoc.dev/document-api/reference/track-changes/decide)

## Toggling tracked edits

Control recording via document mode:

```javascript theme={null}
superdoc.setDocumentMode("suggesting"); // record new edits as tracked changes
superdoc.setDocumentMode("editing"); // stop recording
superdoc.setDocumentMode("viewing"); // read-only
```

## Change types

| Type | Mark | Visual |
| - | - | - |
| Insertion | `trackInsert` | Underlined in the reviewer's color |
| Deletion | `trackDelete` | Strikethrough in the reviewer's color |
| Format change | `trackFormat` | Records the before/after formatting on the run |

Each mark carries `id`, `author`, `authorEmail`, `date`, and: for imports from Word: the original `w:id` as `sourceId` so you can round-trip revision provenance.

## Events

Tracked-change events are delivered through the same `onCommentsUpdate` callback as comment events. The top-level `type` field tells them apart; filter on `type === 'trackedChange'` and read the flat payload.

```javascript theme={null}
onCommentsUpdate: (payload) => {
  if (payload.type !== "trackedChange") return;

  switch (payload.event) {
    case "add":
      // New tracked change created.
      break;
    case "update":
      // Existing tracked change updated (e.g. reply added, author edited).
      break;
    case "change-accepted":
      await markAccepted(payload.changeId);
      break;
    case "change-rejected":
      await markRejected(payload.changeId);
      break;
    case "resolved":
      // Tracked-change comment thread resolved.
      break;
  }
};
```

### Payload fields

**payload** `Object`

**Fields**

**type** `'trackedChange'`

Always `'trackedChange'` for tracked-change events. Comment events use other values.

**event** `string`

Event kind: `'add'`, `'update'`, `'deleted'`, `'resolved'`, `'selected'`, `'change-accepted'`, or `'change-rejected'`.

**changeId** `string`

The tracked-change id (matches `TrackChangeInfo.id` returned by `trackChanges.list()`).

**trackedChangeType** `'trackInsert' | 'trackDelete' | 'trackFormat' | 'both'`

The mark type. `'both'` is used for a paired replacement (insertion and deletion together).

**trackedChangeText** `string`

The inserted or affected text.

**deletedText** `string | null`

The deleted text, for deletions and replacements.

**trackedChangeDisplayType** `string`

A human-facing summary derived from the change (e.g. `'hyperlinkAdded'`, `'formatChanged'`).

**author** `string`

Display name.

**authorEmail** `string`

Email.

**authorImage** `string`

Avatar URL, when provided.

**date** `string`

ISO timestamp.

**documentId** `string`

Source document id.

**importedAuthor** `Object | null`

Original author info from the imported DOCX, when available: `{ name }`.

> [!NOTE]
>
> Events fire once per user action, not once per mark. A tracked replacement in paired mode emits one event with `trackedChangeType: 'both'`. To enumerate the current set of revisions, use `editor.doc.trackChanges.list()`: not the event stream.

## Permissions

Accept and reject permissions are governed by the same `permissionResolver` used for comments. Return `false` from the resolver to block an action.

```javascript theme={null}
modules: {
  comments: {
    permissionResolver: ({ permission, trackedChange, currentUser, defaultDecision }) => {
      if (
        permission === "REJECT_OTHER" &&
        trackedChange?.attrs?.authorEmail !== currentUser?.email
      ) {
        return false;
      }
      return defaultDecision;
    },
  },
}
```

Tracked-change permission types:

| Permission | Description |
| - | - |
| `RESOLVE_OWN` | Accept your own tracked changes |
| `RESOLVE_OTHER` | Accept other users' tracked changes |
| `REJECT_OWN` | Reject your own tracked changes |
| `REJECT_OTHER` | Reject other users' tracked changes |

See [Comments → Permission resolver](https://docs.superdoc.dev/editor/built-in-ui/comments.md#permission-resolver) for the full list of permission types and resolver behavior.

## Word import/export

Tracked changes round-trip through DOCX as native Word revisions. Import it. Edit it. Export it. Nothing lost.

```javascript theme={null}
// Export with revisions preserved. Word opens the file and shows the
// insertions and deletions under Review.
const blob = await superdoc.export();

// Accept all first, then export a clean copy.
superdoc.activeEditor.doc.trackChanges.decide({
  decision: "accept",
  target: { scope: "all" },
});
const cleanBlob = await superdoc.export();
```

Imported Word revisions preserve their original `w:id` values as `wordRevisionIds` on each `TrackChangeInfo` entry, so you can correlate SuperDoc revisions with the source document or an external review system.

> [!NOTE]
>
> Round-trip support today covers inserted run content (`<w:ins>`), deleted run content (`<w:del>`), and run-level format changes (`<w:rPrChange>`). Paragraph-level property changes, tracked table row and cell edits, and tracked moves are on the roadmap: they import as accepted content today.

## Legacy editor commands

> [!WARNING]
>
> **Deprecated**. Use the [Document API](#document-api) (`editor.doc.trackChanges.list()`, `editor.doc.trackChanges.decide(...)`) instead. The commands below remain available but will be removed in a future release.

These legacy commands live on `superdoc.activeEditor.commands` and predate the Document API. They're still used by the built-in toolbar and a handful of keyboard shortcuts.

### Enable and toggle

```javascript theme={null}
superdoc.activeEditor.commands.enableTrackChanges();
superdoc.activeEditor.commands.disableTrackChanges();
superdoc.activeEditor.commands.toggleTrackChanges();
```

### Accept

```javascript theme={null}
superdoc.activeEditor.commands.acceptTrackedChangeBySelection();
superdoc.activeEditor.commands.acceptTrackedChangeById("change-123");
superdoc.activeEditor.commands.acceptTrackedChangesBetween(10, 50);
superdoc.activeEditor.commands.acceptAllTrackedChanges();
superdoc.activeEditor.commands.acceptTrackedChangeFromToolbar();
```

### Reject

```javascript theme={null}
superdoc.activeEditor.commands.rejectTrackedChangeOnSelection();
superdoc.activeEditor.commands.rejectTrackedChangeById("change-123");
superdoc.activeEditor.commands.rejectTrackedChangesBetween(10, 50);
superdoc.activeEditor.commands.rejectAllTrackedChanges();
superdoc.activeEditor.commands.rejectTrackedChangeFromToolbar();
```

### Insert a tracked change programmatically

```javascript theme={null}
superdoc.activeEditor.commands.insertTrackedChange({
  from: 10,
  to: 25,
  text: "replacement text",
  comment: "AI suggestion: improved wording",
});
```

**options** `Object` *required*

**Options**

**from** `number` *required*

Start of the range.

**to** `number` *required*

End of the range. When `from === to`, the change is a pure insertion.

**text** `string`

Replacement text. Omit or leave empty for a pure deletion.

**id** `string`

Explicit id for the change. Defaults to a generated UUID.

**user** `Object`

Author override (`{ name, email, image? }`). Defaults to the editor's `user` option.

**comment** `string`

Optional comment to attach.

**addToHistory** `boolean` (default: true)

Record the transaction in the undo stack.

**emitCommentEvent** `boolean` (default: true)

Emit a `trackedChange` event through `onCommentsUpdate`.

### View modes

Temporarily render the document without applying revisions: useful for previewing the accepted or original state:

```javascript theme={null}
// Show the document as it was before tracked changes.
superdoc.activeEditor.commands.enableTrackChangesShowOriginal();
superdoc.activeEditor.commands.disableTrackChangesShowOriginal();
superdoc.activeEditor.commands.toggleTrackChangesShowOriginal();

// Show the document with all changes accepted.
superdoc.activeEditor.commands.enableTrackChangesShowFinal();
superdoc.activeEditor.commands.toggleTrackChangesShowFinal();
```

## Full example

> [card] [Track Changes Example](https://go.superdoc.dev/track-changes)
>
> Runnable example: mode switching, accept and reject, comments sidebar, DOCX import and export.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.