Tracked Changes on the whiteboard

Shapes are nodes, so they can carry the suggestions of Tracked Changes, like a note that an AI agent suggests. The board shows those suggestions on the shapes, and the commands of Tracked Changes review them.

Set up the editor

Install Tracked Changes, and add it to the board's editor. Pass getSuggestionHTMLAttributes from Tracked Changes as the shapeElementAttributes option of WhiteboardKit:

import { Editor } from '@tiptap/core'
import { getSuggestionHTMLAttributes, TrackedChanges } from '@tiptap-pro/extension-tracked-changes'
import { WhiteboardKit } from '@tiptap-pro/extension-whiteboard'

const editor = new Editor({
  element: viewport,
  extensions: [
    WhiteboardKit.configure({ shapeElementAttributes: getSuggestionHTMLAttributes }),
    TrackedChanges,
  ],
})

In React, create the configured kit once, outside the component or with useMemo. See Set up a board in React.

shapeElementAttributes adds attributes to the element of every shape, from the shape's node. With getSuggestionHTMLAttributes, the element of a shape that a suggestion changes gets data-suggestion-* attributes, like data-suggestion-type and data-suggestion-user.

Tracked Changes starts with enabled: false. Edits on the board then apply directly, and the board shows the suggestions that shapes carry.

Show suggestions

Style the shapes that suggestions change with the attributes on their elements:

/* A shape that a suggestion adds */
[data-shape][data-suggestion-type='add'] {
  outline: calc(2px / var(--zoom, 1)) dashed #2b9a66;
}

/* A shape that a suggestion deletes */
[data-shape][data-suggestion-type='delete'] {
  opacity: 0.5;
}

/* A shape that a suggestion moves or changes */
[data-shape][data-suggestion-type='attributeChange'] {
  outline: calc(2px / var(--zoom, 1)) dashed #0d74ce;
}

The attributes go away once the suggestion is reviewed. Suggestions in the text of a shape show like in any other document. See Styling for all attributes.

Review suggestions

Find suggestions with findSuggestions, and accept or reject them by id:

import { findSuggestions } from '@tiptap-pro/extension-tracked-changes'

const [suggestion] = findSuggestions(editor)

if (suggestion) {
  editor.commands.acceptSuggestion({ id: suggestion.id })
}

A suggestion that adds shapes lists them in insertedNodes, like { type: 'stickyNote' }. When a suggestion adds several shapes, like all the notes that one AI tool call adds, one id accepts or rejects them all.

When a rejected suggestion removes a shape, the arrows that connected it keep a free end. Reviews work in collaborative boards too: all users see the suggestion, and a review applies everywhere.

Next steps

• See all commands of Tracked Changes
• Let an AI agent suggest changes with the Server AI Toolkit
• Learn about shapeElementAttributes