Install the Tracked Changes extension

Install and configure the Tracked Changes extension by following this guide.

Install

npm install @tiptap-pro/extension-tracked-changes

Basic setup

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

const editor = new Editor({
  extensions: [
    TrackedChanges.configure({
      enabled: true,
      userId: 'user-123',
      userMetadata: { name: 'John Doe' },
    }),
  ],
})

Settings

enabled

Enable or disable track changes mode. When enabled, all edits become suggestions instead of direct changes.

Default: false

TrackedChanges.configure({
  enabled: true,
})

userId

The ID of the current user making suggestions. This should come from your authentication system.

Default: 'anonymous'

TrackedChanges.configure({
  userId: 'user-123',
})

userMetadata

Arbitrary metadata about the current user, stored as a JSON-serializable object on each suggestion. Useful for storing display names, avatars, or other custom data alongside the suggestion without requiring a separate user store.

Default: null

TrackedChanges.configure({
  userId: 'user-123',
  userMetadata: {
    name: 'John Doe',
    avatar: 'https://example.com/avatar.jpg',
    role: 'editor',
  },
})

suggestionGroupingTimeout

Time window in milliseconds for grouping adjacent suggestions. If a user makes continuous edits in the same area within this time window, they will be merged into a single suggestion. Set to 0 to disable grouping.

Default: 2000

TrackedChanges.configure({
  suggestionGroupingTimeout: 3000,
})

onSuggestionCreate

Callback fired when a new suggestion is created. Receives the suggestion object containing id, type, userId, createdAt, from, to, and text.

Default: undefined

TrackedChanges.configure({
  onSuggestionCreate: (suggestion) => {
    console.log('New suggestion created:', suggestion)
    // Update your UI, notify other users, etc.
  },
})

onSuggestionAccept

Callback fired when a suggestion is accepted. Receives the suggestion ID.

Default: undefined

TrackedChanges.configure({
  onSuggestionAccept: (id) => {
    console.log('Suggestion accepted:', id)
  },
})

onSuggestionReject

Callback fired when a suggestion is rejected. Receives the suggestion ID.

Default: undefined

TrackedChanges.configure({
  onSuggestionReject: (id) => {
    console.log('Suggestion rejected:', id)
  },
})