Tiptap Docs

Diff utility

diffUtility

Compares two documents and returns a list of changes between them.

Supported formats

The Diff Utility can be used to compare entire documents or parts of them.

To compare entire documents, you can provide them in Tiptap JSON format or as a ProseMirror Node.

To compare parts of the document, you can provide them as a Tiptap JSON fragment (a list of Tiptap JSON nodes) or as a ProseMirror Fragment.

Parameters (DiffUtilityOptions)

  • schema (Schema): The ProseMirror schema used in the editor. Can be obtained from the editor instance: editor.schema
  • docA (Node | Fragment | JSONContent | JSONContent[]): Original document. Can be a ProseMirror Node/Fragment or Tiptap JSON
  • docB (Node | Fragment | JSONContent | JSONContent[]): Modified document. Can be a ProseMirror Node/Fragment or Tiptap JSON
  • simplifyChanges? (boolean): Whether to simplify the changes so that if there are multiple changes in the same word, they are merged into one 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'

Schema issue

Both documents must have the same schema. If the documents come from different editors, convert them to a common editor schema: Node.fromJSON(editor.state.schema, otherEditor.getJSON())

Returns (Change[])

Returns a list of changes. Each Change item contains:

  • rangeA (Range): The range in the original document that has changed
  • rangeB (Range): The range in the modified document that has changed

Example 

import { diffUtility } from '@tiptap-pro/ai-toolkit'

// Compute changes between two documents
const changes = diffUtility({
  schema: editor.schema,
  docA,
  docB,
})

// Use block-level diffing
const blockChanges = diffUtility({
  schema: editor.schema,
  docA,
  docB,
  mode: 'block',
})
PreviouslyCompare documents