Visually compare snapshots of your documents

Tired of playing "spot the difference" with your document versions?

The Snapshot Compare extension adds extra functionality to the Document History by allowing you to visually compare changes made between two versions of a document so you can track what’s been added, removed, or modified. These comparisons are called diffs.

Whether you're collaborating with a team or editing solo, this helps you track changes over time and understand who made specific edits. By highlighting differences within the editor and attributing them to their authors, Snapshot Compare brings transparency and efficiency to the document lifecycle.

Install

Install the extension from our private registry:

npm install @tiptap-pro/extension-snapshot-compare

Settings

You can configure the SnapshotCompare extension with the following options:

const provider = new TiptapCollabProvider({
  // ...
})

const editor = new Editor({
  // ...
  extensions: [
    // ...
    SnapshotCompare.configure({
      provider,
    }),
  ],
})

Storage

The SnapshotCompare storage object contains the following properties:

Use the isPreviewing property to check if the diff view is currently active:

if (editor.storage.snapshotCompare.isPreviewing) {
  // The diff view is currently active
}

Use the diffs property to access the diffs displayed in the diff view:

editor.storage.snapshotCompare.diffs

The property previousContent is used internally by the extension to restore the content when exiting the diff view. Typically, you do not need to interact with it directly.

Commands

compareVersions

Use the compareVersions command to compute and display the differences between two document versions.

editor.chain().compareVersions({
  fromVersion: 1,
})

Options

You can pass in additional options for more control over the diffing process:

Using hydrateUserData to add metadata

Each diff has an attribution field, which allows you to add additional metadata with the hydrateUserData callback function.

Example: Color-coding diffs based on user

const colorMapping = new Map([
  ['user-1', '#ff0000'],
  ['user-2', '#00ff00'],
  ['user-3', '#0000ff'],
])

editor.chain().compareVersions({
  fromVersion: 1,
  toVersion: 3,
  hydrateUserData: ({ userId }) => {
    return {
      color: {
        backgroundColor: colorMapping.get(userId),
      },
    }
  },
})

editor.storage.snapshotCompare.diffs[0].attribution.color.backgroundColor // '#ff0000'

Using mapDiffToDecorations for diff decorations

The extension has a default mapping (defaultMapToDecorations) to represent diffs as ProseMirror decorations. For more complex integrations and control, you can customize this mapping with the mapDiffToDecorations option.

Example: Applying custom predefined background colors to inline inserts

editor.chain().compareVersions({
  fromVersion: 1,
  toVersion: 3,
  mapDiffToDecorations: ({ diff, tr, editor, defaultMapToDecorations }) => {
    if (diff.type === 'inline-insert') {
      // return prosemirror decoration(s) or null
      return Decoration.inline(
        diff.from,
        diff.to,
        {
          class: 'diff',
          style: {
            backgroundColor: diff.attribution.color.backgroundColor,
          },
        },
        // pass the diff as the decoration's spec, this is required for `extractAttributeChanges`
        { diff },
      )
    }

    // fallback to the default mapping
    return defaultMapToDecorations({ diff, tr, editor })
  },
})

Using onCompare to customize the diffing process

If you need more control over the diffing process, use the onCompare option to receive the result and handle it yourself.

Example: Filtering diffs by user

editor.chain().compareVersions({
  fromVersion: 1,
  toVersion: 3,
  onCompare: (ctx) => {
    if (ctx.error) {
      // handle errors that occurred in the diffing process
      console.error(ctx.error)
      return
    }

    // filter the diffs to display only the changes made by a specific user
    const diffsToDisplay = ctx.diffSet.filter((diff) => diff.attribution.userId === 'user-1')

    editor.commands.showDiff(ctx.tr, { diffs: diffsToDisplay })
  },
})

showDiff

Use the showDiff command to display the diff within the editor using a change tracking transform (tr). This represents all of the changes made to the document since the last snapshot. You can use this transform to show the diff in the editor.

Typically, you use this command after customizing or filtering diffs with compareVersions, onCompare.

The showDiff command temporarily replaces the current editor content with the diff view, showing the differences between versions. It also stashes the content currently displayed in editor so that you can restore it later.

// This will display the changes that change tracking transform recorded in the editor
editor.commands.showDiff(tr)

Options

You can pass additional options to control how the diffs are displayed:

Example: Displaying specific diffs

// This will display only the diffs made by the user with the ID 'user-1'
const diffsToDisplay = tr.toDiff().filter((diff) => diff.attribution.userId === 'user-1')

editor.commands.showDiff(tr, { diffs: diffsToDisplay })

hideDiff

Use the hideDiff command to hide the diff and restore the previous content.

// This will hide the diff view and restore the previous content
editor.commands.hideDiff()

Working with NodeView (Advanced)

When using custom node views, the default diff mapping may not work as expected. You can customize the mapping and render the diffs directly within the custom node view.

Use the extractAttributeChanges helper to extract attribute changes in nodes. This allows you to access the previous and current attributes of a node, making it possible to highlight attribute changes within your custom node views.

Example: Customizing a heading node view to display changes

import { extractAttributeChanges } from '@tiptap-pro/extension-snapshot-compare'

const Heading = BaseHeading.extend({
  addNodeView() {
    return ReactNodeViewRenderer(({ node, decorations }) => {
      const { before, after, isDiffing } = extractAttributeChanges(decorations)

      return (
        <NodeViewWrapper style={{ position: 'relative' }}>
          {isDiffing && before.level !== after.level && (
            <span
              style={{
                position: 'absolute',
                right: '100%',
                fontSize: '14px',
                color: '#999',
                backgroundColor: '#f0f0f070',
              }}
              // Display the difference in level attribute
            >
              #<s>{before.level}</s>
              {after.level}
            </span>
          )}
          <NodeViewContent as={`h${node.attrs.level ?? 1}`} />
        </NodeViewWrapper>
      )
    })
  },
})

Technical details

Diff

A Diff is an object that represents a change made to the document. It contains the following properties:

DiffSet

A DiffSet is an array of Diff objects, each corresponding to a specific change, like insertion, deletion, or update. You can iterate over the array to inspect individual changes or apply custom logic based on the diff types.

const diffsToDisplay = diffSet.filter((diff) => diff.attribution.userId === 'user-1')

// Show the filtered diffs in the editor
editor.commands.showDiff(tr, { diffs: diffsToDisplay })

Attribution

The Attribution object contains metadata about a change. It includes the following properties:

You can extend the Attribution interface to include additional properties:

declare module '@tiptap-pro/extension-snapshot-compare' {
  interface Attribution {
    userName: string
  }
}

ChangeTrackingTransform

The ChangeTrackingTransform is a class that records changes made to the document (based on ProseMirror's Transform). It represents a transform whose steps describe all of the changes made to go from one version of the document to another. It has the following properties:

ChangeTrackingStep

The ChangeTrackingStep is a class that represents a single change made to the document, based on ProseMirror's ReplaceStep class. It has the following property: