Compare documents

Compare two documents in real time and show the diff in the editor.

Guide: compare two documents

Start by calling the startComparingDocuments method. It compares the current document of the editor with another document of your choice. The method takes one parameter: otherDoc, the document to compare against.

const toolkit = getAiToolkit(editor)

// Start comparing changes with another document
toolkit.startComparingDocuments({
  otherDoc,
})

If otherDoc is not provided, the AI Toolkit will start tracking the changes in the current document from the moment that startComparingDocuments was called, and display a diff of the document before and after the changes.

The diff is displayed as suggestions in the editor. Add this CSS file to your app to format suggestions as a red and green diff:

/* Highlight inserted text in green */
.tiptap-ai-suggestion,
.tiptap-ai-suggestion > * {
  background-color: oklch(87.1% 0.15 154.449);
}

/* Highlight deleted text in red */
.tiptap-ai-suggestion-diff,
.tiptap-ai-suggestion-diff > * {
  background-color: oklch(80.8% 0.114 19.571);
}

Call getSuggestions to get a list of each individual change between the documents, stored as suggestions. Then, call acceptChange or rejectChange to accept or reject them individually.

// Get all changes (as suggestions)
const suggestions = toolkit.getSuggestions()

// Accept the first change
toolkit.acceptChange(suggestions[0].id)

// Reject the first change
toolkit.rejectChange(suggestions[0].id)

To stop comparing documents, use the stopComparingDocuments method. It hides the diff view and clears the suggestions.

toolkit.stopComparingDocuments()

Example demo

Below is a demo of how to compare two documents in real time.

Try clicking the "Start comparing documents" button, and a diff will appear. Then, try editing the document and see the diff change.

API reference

startComparingDocuments

Starts real-time comparison with another document. Differences are displayed as suggestions in an inline diff view where the old and the new content are displayed in the editor.

Parameters (StartComparingDocumentsOptions)

• otherDoc? (Node): The document to compare against. It is a ProseMirror Node object. Defaults to a snapshot of the current document if omitted
• displayOptions? (DisplayOptions<{ suggestion: Suggestion }>): Controls how differences are rendered as suggestions
  • showAsDiff? (boolean): Show alternative content as a diff widget. Default: true in comparison flows
  • diffPosition? ('before' | 'after'): Where to display the diff relative to the suggestion. Default: 'before'
  • attributes? (Record<string, any>): Attributes added to rendered elements
  • renderDecorations? (RenderDecorations<{ suggestion: Suggestion }>): Custom rendering function
• debounceTimeout? (number): Milliseconds to wait before recomputing diffs. A low value will make the app seem more responsive, but it might cause performance issues in large documents. Default: 500

Returns

void

Example

// Start comparing changes with another document
toolkit.startComparingDocuments({
  otherDoc,
})

stopComparingDocuments

Stops the real-time comparison and clears all suggestions, so the diff view is no longer visible.

Returns

void

Example

// Stop comparison and clear decorations
toolkit.stopComparingDocuments()

acceptChange

Accepts a change so that it is no longer visible in the diff when comparing documents in real-time.

This is equivalent to applying a specific suggestion by its ID to the other document. The "other document" or otherDoc is the document that is being compared to the current document.

To accept all changes, call stopComparingDocuments. This will hide the diff view, as if all changes had been accepted.

Parameters

• suggestionId (string): The unique identifier of the suggestion that represents the change to accept

Returns

void

Example

// Start comparing documents
toolkit.startComparingDocuments({
  otherDoc: otherDoc,
})

// Get all changes (as suggestions)
const suggestions = toolkit.getSuggestions()

// Accept the first change
toolkit.acceptChange(suggestions[0].id)

rejectChange

Rejects a change so that it is no longer visible in the diff when comparing documents in real-time.

This is equivalent to applying a specific suggestion by its ID to the current document.

Parameters

• suggestionId (string): The unique identifier of the suggestion that represents the change to reject

Returns

void

Example

// Start comparing documents
toolkit.startComparingDocuments({
  otherDoc: otherDoc,
})

// Get all changes (as suggestions)
const suggestions = toolkit.getSuggestions()

// Reject the first change
toolkit.rejectChange(suggestions[0].id)

rejectAllChanges

Rejects all changes so that they are no longer visible in the diff when comparing documents in real-time.

This is equivalent to setting the current document to the otherDoc.

Returns

void

Example

// Start comparing documents
toolkit.startComparingDocuments({
  otherDoc: otherDoc,
})

// Reject all changes
toolkit.rejectAllChanges()