Report an issue

guideTrack changes overview

This feature enables the track changes mode (also known as the “suggestion mode”) in CKEditor 5.

In this mode, changes done by users are marked in the content and shown as suggestions in the sidebar. Suggestions can be accepted or discarded by the users. The suggestion balloon is then closed and the change is no longer marked.

Suggestion annotations can be displayed in a sidebar or as inline balloons. Visit the display mode guide to learn how to configure the display mode. The mode specified for comments is also set for track changes.

This sample automatically switches between display modes according to the screen size. Resize the window and observe how the editor changes its appearance.

# Use as a standalone plugin

Track changes does not require real-time collaboration to work. If you prefer a more traditional approach with asynchronous document editing, track changes can be added to CKEditor 5 just like any other plugin.

To learn how to integrate track changes as a standalone plugin, please refer to the Integrating track changes with your application guide.

# Use with real-time collaboration

If you are using the real-time collaboration feature, refer to the Real-time collaborative features integration guide.

# Suggestions markup

Suggestions are always attached to some place in the document. To make sure that they will not be lost, the track changes plugin adds some special markup to the document:

<p>
    I like
    <suggestion id="e8ghd7:e390dk" suggestion-type="insertion" type="start"></suggestion>chocolate<suggestion id="e8ghd7:e390dk" suggestion-type="insertion" type="end"></suggestion>
    <suggestion id="ejd853:e390dk" suggestion-type="deletion" type="start"></suggestion>ice-creams<suggestion id="ejd853:e390dk" suggestion-type="deletion" type="end"></suggestion>.
</p>

The position of a suggestion in the content is marked with a custom <suggestion> tag. Separate elements for the beginning and the end of a suggestion are used to make it easier to process the content (e.g. before rendering it on your website).

Note that if your application filters HTML content, for example to prevent XSS, make sure to leave the <suggestion> tags in place when saving the content in the database. The suggestion markup is necessary for further editing sessions.

If you need to show the content without unaccepted suggestions to the end user, you can parse the content and filter out suggestions. Here is a simplified solution that can be used:

  • Insertions – For each insertion <suggestion> start tag (<suggestion id="..." suggestion-type="insertion" type="start"></suggestion>) find the next <suggestion> tag with the same id and remove the tags and all the content between them.
  • Deletions – Remove all deletion <suggestion> tags (<suggestion suggestion-type="deletion" ... ></suggestion>).
  • Inline formatting – Remove all inline formatting <suggestion> tags (<suggestion suggestion-type="formatInline:..." ... ></suggestion>).
  • Block formatting – Remove all block formatting <suggestion> tags (<suggestion suggestion-type="formatBlock:..." ... ></suggestion>).

Given the example content above, after processing the HTML should equal to:

<p>I like ice-creams.</p>

We are working on an API that will provide the above functionality directly in the editor to make it possible to save content both with and without the suggestions.

When launching the editor, though, make sure to include the <suggestion> tags in the HTML:

<div id="container">
    <div id="editor">
        <p>
            I like
            <suggestion id="e8ghd7:e390dk" suggestion-type="insertion" type="start"></suggestion>chocolate<suggestion id="e8ghd7:e390dk" suggestion-type="insertion" type="end"></suggestion>
            <suggestion id="ejd853:e390dk" suggestion-type="deletion" type="start"></suggestion>ice-creams<suggestion id="ejd853:e390dk" suggestion-type="deletion" type="end"></suggestion>.
        </p>
    </div>
    <div id="sidebar"></div>
</div>

# Commands

The track changes plugin adds a set of commands to the editor. These commands are executed when you turn on the track changes mode, accept a suggestion, etc. You do not need to care about the commands if you are integrating the track changes plugin together with the UI part. However, knowing about them might be useful if you are working on a custom UI.

The following commands are available:

  • trackChanges – Toggles the track changes mode in the editor.
  • acceptSuggestion – Accepts a suggestion with the specified ID.
  • discardSuggestion – Discards a suggestion with the specified ID.
  • acceptAllSuggestions – Accepts all suggestions.
  • discardAllSuggestions – Discards all suggestions.

Examples:

editor.execute( 'trackChanges' );
editor.execute( 'acceptSuggestion', 'suggestion-1' );
editor.execute( 'discardSuggestion', 'suggestion-1' );
editor.execute( 'acceptAllSuggestions' );
editor.execute( 'discardAllSuggestions' );

Note that there is no command to add a suggestion. This is because suggestions are added automatically when editing commands are executed while the editor is in track changes mode. For instance:

// Turn on the track changes mode.
editor.execute( 'trackChanges' );

// Insert some text. It will be automatically inserted as a suggestion.
editor.execute( 'input', { text: 'foo' } );

# Theme customization

Like in the whole CKEditor 5 Ecosystem, we have used CSS Variables to let the developers easily customize the design of such UI elements as, for example, suggestion markers. You can easily override these properties with a .css file or place your customizations directly into the <head> section of your page, but in this case you will need to use a more specific CSS selector than :root (e.g. <body>).

Check out the color sheet for the full list of customizable colors. You can also browse other files with CSS Variables in CKEditor 5.

Here you can find the default CSS Variables used for the track changes feature:

:root {
    /* You can override the design of suggestion markers in the content. */

    /* Variables responsible for suggestions for text: */
    --ck-color-suggestion-marker-insertion-border: hsla(128, 71%, 40%, .5);
    --ck-color-suggestion-marker-insertion-border-active: hsla(128, 71%, 25%, .5);
    --ck-color-suggestion-marker-insertion-background: hsla(128, 71%, 65%, .5);
    --ck-color-suggestion-marker-insertion-background-active: hsla(128, 71%, 50%, .5);

    --ck-color-suggestion-marker-deletion-border: hsla(345, 71%, 40%, .5);
    --ck-color-suggestion-marker-deletion-border-active: hsla(345, 71%, 25%, .5);
    --ck-color-suggestion-marker-deletion-background: hsla(345, 71%, 65%, .5);
    --ck-color-suggestion-marker-deletion-background-active: hsla(345, 71%, 50%, .5);
    --ck-color-suggestion-marker-deletion-stroke: hsla(345, 71%, 20%, .5);

    --ck-color-suggestion-marker-format-border: hsla(191, 90%, 40%, .4);
    --ck-color-suggestion-marker-format-border-active: hsla(191, 90%, 40%, .65);

    /* Variables responsible for the left border of the suggestion boxes in the sidebar: */
    --ck-color-comment-box-border: hsl(55, 98%, 48%);
    --ck-color-suggestion-box-deletion-border: hsl(345, 62%, 60%);
    --ck-color-suggestion-box-insertion-border: hsl(128, 62%, 60%);

    /* Variables responsible for the styling of suggestions for widgets: */
    --ck-color-suggestion-insertion-image-background: hsla(128, 71%, 65%, .05);
    --ck-color-suggestion-insertion-image-background-active: hsla(128, 71%, 50%, .07);
    --ck-color-suggestion-insertion-image-caption-background: hsla(128, 71%, 65%, .07);
    --ck-color-suggestion-insertion-image-caption-background-active: hsla(128, 71%, 50%, .07);
    --ck-color-suggestion-deletion-image-background: hsla(345, 71%, 65%, .05);
    --ck-color-suggestion-deletion-image-background-active: hsla(345, 71%, 45%, .07);
    --ck-color-suggestion-deletion-image-caption-background: hsla(345, 71%, 65%, .06);
    --ck-color-suggestion-deletion-image-caption-background-active: hsla(345, 71%, 45%, .06);

    --ck-color-suggestion-insertion-td-background: hsla(128, 71%, 65%, .05);
    --ck-color-suggestion-insertion-td-background-active: hsla(128, 71%, 50%, .07);
    --ck-color-suggestion-insertion-th-background: hsla(128, 71%, 65%, .1);
    --ck-color-suggestion-insertion-th-background-active: hsla(128, 71%, 50%, .12);
    --ck-color-suggestion-deletion-td-background: hsla(345, 71%, 65%, .05);
    --ck-color-suggestion-deletion-td-background-active: hsla(345, 71%, 45%, .07);
    --ck-color-suggestion-deletion-th-background: hsla(345, 71%, 65%, .1);
    --ck-color-suggestion-deletion-th-background-active: hsla(345, 71%, 45%, .12);

    --ck-color-suggestion-insertion-media-background: hsla(128, 71%, 65%, .05);
    --ck-color-suggestion-insertion-media-background-active: hsla(128, 71%, 50%, .07);
    --ck-color-suggestion-deletion-media-background: hsla(345, 71%, 65%, .05);
    --ck-color-suggestion-deletion-media-background-active: hsla(345, 71%, 45%, .07);
}

If you want to change the appearance of a single suggestion box (placed in the sidebar), refer to the comments theme customization guide.