Compare documents with Tracked Changes

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

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.

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 to accept or reject them.

Compare versions

Use compareVersions to compare two Yjs version updates. You can then display the diff in the editor using Tracked Changes suggestions.

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 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 to learn how to send the documents and schema to your server.

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.