---
title: "Diff utility"
description: "Compute changes between two documents programmatically."
canonical_url: "https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/api-reference/diff-utility"
---

# Diff utility

Compute changes between two documents programmatically.

## `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](https://tiptap.dev/docs/editor/core-concepts/introduction.md#content) or as a [ProseMirror Node](https://prosemirror.net/docs/ref/#model.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](https://prosemirror.net/docs/ref/#model.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. Does not apply when mode is `'block'`. Default: `true`
- `ignoreAttributes?` (`string[]`): The attributes to ignore. Default: `['id', 'data-thread-id']`
- `ignoreMarks?` (`string[]`): The marks to ignore. Default: `['inlineThread']`
- `changeMergeDistance?` (`number | null`): Minimum length for an unchanged range to be considered significant. Unchanged ranges shorter than this value will be absorbed into adjacent changes, merging them into a single change. Set to `null` or `undefined` to use the auto-calculated default. Does not apply when mode is 'block'. Default: `10`
- `groupInlineChanges?` (`number`): Controls when inline edits are grouped into one block-level change in `smart` mode. Use `1` (default) to group only when all inline content changed, `0` to always group, and `2` to never group.
- `mode?` (`'smart' | 'inline' | 'block'`): The diff mode to use for comparison.
  - `'smart'` (default) balances block-level and inline-level output for readable review suggestions.
  - `'inline'` performs character-level diff that identifies precise changes within text.
  - `'block'` performs block-level diff that treats each top-level node as a single unit. In block mode, `simplifyChanges` and `changeMergeDistance` are ignored.

In the playground below, click on the "Show diff options" button and see how each option affects the diff:

> **Interactive demo:** [React](https://deploy-preview-405--tiptap-pro.netlify.app/src/Extensions/AiToolkitCompareDocuments/React/)

### 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

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

// Compute changes between two documents (uses 'smart' mode by default)
const changes = diffUtility({
  schema: editor.schema,
  docA,
  docB,
})

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

// Use inline (character-level) diffing
const inlineChanges = diffUtility({
  schema: editor.schema,
  docA,
  docB,
  mode: 'inline',
})
```

# Compare documents in real-time

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

> **Works in non-AI use cases:**
>
> This feature does not need AI to work. It can compare any two documents, regardless of whether
> they are AI-generated or not.

For a step-by-step guide on comparing documents, see the [Compare documents guide](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/advanced-guides/compare-documents.md).

## `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](https://prosemirror.net/docs/ref/#model.Node). Defaults to a snapshot of the current document if omitted
- `displayOptions?` (`DisplayOptions`): Controls how differences are rendered as suggestions. [See available options](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/api-reference/suggestions.md#the-suggestion-object).
- `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`
- `diffUtilityOptions?` ([`ExternalDiffUtilityOptions`](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/api-reference/diff-utility.md#parameters-diffutilityoptions)): Options for comparing the documents with the diff utility. [See available options](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/api-reference/diff-utility.md#parameters-diffutilityoptions).

### Returns

`void`

### Example

```ts
// 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

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

## Accepting and rejecting changes

When comparing documents, changes are displayed as suggestions. To accept or reject individual changes or all changes at once, use the suggestion methods:

- [`acceptSuggestion`](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/api-reference/suggestions.md#acceptsuggestion): Accept a specific change
- [`rejectSuggestion`](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/api-reference/suggestions.md#rejectsuggestion): Reject a specific change
- [`acceptAllSuggestions`](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/api-reference/suggestions.md#acceptallsuggestions): Accept all changes
- [`rejectAllSuggestions`](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/api-reference/suggestions.md#rejectallsuggestions): Reject all changes

See the [Compare documents guide](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/advanced-guides/compare-documents.md) for a usage example.