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.

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()