---
title: "Compare documents with Tracked Changes"
description: "Display document comparisons as tracked changes that users can accept or reject."
canonical_url: "https://tiptap.dev/docs/compare/guides/tracked-changes"
---

# Compare documents with Tracked Changes

Display document comparisons as tracked changes that users can accept or reject.

Display a document comparison as tracked changes so users can review, accept, or reject each change individually.

> **Separate product:**
>
> [Tracked Changes](https://tiptap.dev/docs/tracked-changes/getting-started/overview.md) is a different Tiptap product from
> Compare, sold separately.

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

## Compare documents

Add `Compare` and `TrackedChanges` to the editor that displays the comparison. Use the `compareDocuments` utility to compare the documents, then pass the result to the `displayChangesetAsTrackedChanges` editor command.

```ts
import { Editor } from '@tiptap/core'
import { Compare, compareDocuments } from '@tiptap-pro/compare'
import { TrackedChanges } from '@tiptap-pro/extension-tracked-changes'

// The editor where the diff will be displayed
const editor = new Editor({
  extensions: [
    Compare,
    TrackedChanges.configure({ enabled: true }),
    // ...other extensions shared by both documents
  ],
})

const changeset = compareDocuments({
  schema: editor.schema,
  docA, // Original Tiptap JSON document
  docB, // Changed Tiptap JSON document
})

editor.commands.displayChangesetAsTrackedChanges({ changeset })
```

The editor now displays the changes between the two documents as Tracked Changes suggestions. Use the [Tracked Changes commands](https://tiptap.dev/docs/tracked-changes/api-reference/commands.md) to [accept or reject them](https://tiptap.dev/docs/tracked-changes/usage/basic-usage.md#accepting-and-rejecting-suggestions).

> **Tracked Changes must be enabled:**
>
> Before calling the `displayChangesetAsTrackedChanges` command, make sure Tracked Changes is enabled. For example, by initializing the extension like this: `TrackedChanges.configure({ enabled: true })`

## Compare versions

Use [`compareVersions`](https://tiptap.dev/docs/compare/api-reference/utilities.md#compareversions) to compare two Yjs version updates. You can then display the diff in the editor using Tracked Changes suggestions.

```ts
import { compareVersions } from '@tiptap-pro/compare'

const changeset = compareVersions({
  schema: editor.schema,
  versionA, // Older Yjs update
  versionB, // Newer Yjs update
})

editor.commands.displayChangesetAsTrackedChanges({ changeset })
```

The `compareVersions` utility captures user attribution data for each change and stores it in the `userId` property of that change's metadata. This data is automatically transferred to the Tracked Changes suggestions, allowing the Tracked Changes review UI to show who authored each change.

See the [Compare versions](https://tiptap.dev/docs/compare/guides/compare-versions.md) guide for more information about retrieving and showing version updates.

## Create tracked changes on the server

Use `TrackedChangesDocumentFactory` when you need a document with tracked changes without an editor instance, such as in a server route or web worker. The schema must include the Tracked Changes extension before you serialize it on the client. See [Compare documents on the server](https://tiptap.dev/docs/compare/guides/server-compare.md) to learn how to send the documents and schema to your server.

```ts
import {
  compareDocuments,
  deserializeSchema,
  TrackedChangesDocumentFactory,
} from '@tiptap-pro/compare'

const schema = deserializeSchema(serializedSchema)
const changeset = compareDocuments({ schema, docA, docB })

const { doc, trackedChanges } = new TrackedChangesDocumentFactory().fromChangeset({
  changeset,
  schema,
})
```

`doc` is a Tiptap JSON document with tracked changes encoded in it. `trackedChanges` contains the metadata and document range for each encoded change, which you can use for additional server-side processing.