---
title: "Tracked Changes extension"
description: "Enable track changes and suggestion mode in your Tiptap editor for collaborative editing and document review."
canonical_url: "https://tiptap.dev/docs/editor/extensions/functionality/tracked-changes"
---

# Tracked Changes extension

Enable track changes and suggestion mode in your Tiptap editor for collaborative editing and document review.

The Tracked Changes extension enables suggestion mode for collaborative editing workflows. When enabled, all edits appear as proposals that can be accepted or rejected, similar to change tracking in word processors.

> **More details:**
>
> For more detailed information on how to integrate, install, and configure the Tiptap Tracked
> Changes extension, please visit our [feature page](https://tiptap.dev/docs/tracked-changes/getting-started/overview.md).

> **Experimental:**
>
> This extension is under active development. The API may change in future releases. All versions below 1.0.0 are expected to be unstable, use them at your own risk.

> **Interactive demo:** [TrackedChanges](https://embed-pro.tiptap.dev/preview/Experiments/TrackedChanges)

## Install

```bash
npm install @tiptap-pro/extension-tracked-changes
```

## Basic setup

```js
import { Editor } from '@tiptap/core'
import { TrackedChanges } from '@tiptap-pro/extension-tracked-changes'

const editor = new Editor({
  extensions: [
    TrackedChanges.configure({
      enabled: true,
      userId: 'user-123',
      userMetadata: { name: 'John Doe' },
    }),
  ],
})
```

## Programmatic suggestions

In addition to interactive review workflows, the extension also exposes commands for creating tracked suggestions directly from application logic. Use these commands when you need to insert, delete, or replace content as suggestions without turning tracked changes mode on for every editor interaction. You can also attach a `reason` to programmatic suggestions, which is emitted with the creation event for downstream workflows. Insert and replace commands accept full Tiptap `Content`, so they can work with JSON nodes such as images, not just plain text. Tracked mark commands support both simple formatting marks like `bold` and attributed marks like `link` or `highlight`.

If you also use the [TrailingNode](https://tiptap.dev/docs/editor/extensions/functionality/trailing-node.md) extension, `addTrackedInsertion()` and `addTrackedReplacement()` can set `skipTrailingNode: true` to forward that transaction meta onto the emitted tracked-changes transaction.

```js
editor.commands.addTrackedInsertion({
  from: 7,
  content: 'big ',
  reason: 'Applied assistant suggestion',
})

editor.commands.addTrackedDeletion({
  from: 7,
  to: 12,
  reason: 'Removed deprecated sentence',
})

editor.commands.addTrackedReplacement({
  from: 7,
  to: 12,
  content: 'earth',
  reason: 'Standardized terminology',
  skipTrailingNode: true,
})

editor.commands.addTrackedMark({
  from: 7,
  to: 12,
  markName: 'bold',
  reason: 'Emphasized approved terminology',
})

editor.commands.toggleTrackedMark({
  from: 7,
  to: 12,
  markName: 'link',
  markAttrs: {
    href: 'https://tiptap.dev',
    target: '_blank',
  },
  reason: 'Added canonical reference',
})
```

```js
editor.commands.addTrackedInsertion({
  from: 7,
  content: {
    type: 'image',
    attrs: {
      src: '/example.png',
      alt: 'Example image',
    },
  },
  reason: 'Inserted approved image asset',
})
```

See the [commands reference](https://tiptap.dev/docs/tracked-changes/api-reference/commands.md) for the full API.

## Next steps

- [Install and configure](https://tiptap.dev/docs/tracked-changes/getting-started/install.md) — Full settings reference
- [Basic usage](https://tiptap.dev/docs/tracked-changes/usage/basic-usage.md) — Enable tracking, accept and reject suggestions
- [Advanced usage](https://tiptap.dev/docs/tracked-changes/usage/advanced-usage.md) — Grouping, collaboration, comments integration
- [API Reference](https://tiptap.dev/docs/tracked-changes/api-reference/commands.md) — Commands, events, utilities, and types