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 omitteddisplayOptions?
(DisplayOptions<{ suggestion: Suggestion }>
): Controls how differences are rendered as suggestionsshowAsDiff?
(boolean
): Show alternative content as a diff widget. Default:true
in comparison flowsdiffPosition?
('before' | 'after'
): Where to display the diff relative to the suggestion. Default:'before'
attributes?
(Record<string, any>
): Attributes added to rendered elementsrenderDecorations?
(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
Schema issue
The otherDoc
parameter must have the same schema as the current document. If the other document
comes from another editor, convert it to the target editor schema: otherDoc: Node.fromJSON(editor.state.schema, otherEditor.getJSON())
. See example in the demo above.
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()