Compare documents

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

For a step-by-step guide on comparing documents, see the Compare documents guide.

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
• diffUtilityConfig? (DiffUtilityConfig): Options for comparing the documents with the diff utility
  • simplifyChanges? (boolean): Whether to simplify the changes. If true, the changes will be simplified so that, for example, two changes in the same word are merged into a single change. Only applies when mode is 'detailed'. Default: true
  • ignoreAttributes? (string[]): The attributes to ignore. Default: ['id', 'data-thread-id']
  • ignoreMarks? (string[]): The marks to ignore. Default: ['inlineThread']
  • changeMergeDistance? (number | null): Maximum distance (in document positions) between changes to merge them. If two adjacent changes have a distance less than or equal to this value in either rangeA or rangeB, they will be merged into a single change. Set to null or undefined to disable merging. Only applies when mode is 'detailed'. Default: null
  • mode? ('detailed' | 'block'): The diff mode to use for comparison. 'detailed' performs character-level diff that identifies precise changes within text (default). 'block' performs block-level diff that treats each top-level node as a single unit. Block mode is useful when you only need to know which paragraphs, headings, or other block-level elements have changed, without character-level detail. In block mode, simplifyChanges and changeMergeDistance options are ignored. Default: 'detailed'

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