Track changes overview

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

Rich Text Editor

Bilingual Personality Disorder

This may be the first time you hear about this made-up disorder but it actually isn’t so far from the truth. As recent studies show, the language you speak has more effects on you than you realize. According to the studies, the language a person speaks affects their cognition, feelings, behavior, emotions and hence their personality.

This shouldn’t come as a surprise since we already know that different regions of the brain become more active depending on the activity. The structure, information and especially the culture of languages varies substantially and the language a person speaks is an essential element of daily life.

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

# Track changes feature customization

The track changes feature is highly customizable. Please refer to the Annotation customization section to learn more.

# Markers styling

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%, .35);
    --ck-color-suggestion-marker-insertion-border-active: hsla(128, 71%, 25%, .5);
    --ck-color-suggestion-marker-insertion-background: hsla(128, 71%, 65%, .35);
    --ck-color-suggestion-marker-insertion-background-active: hsla(128, 71%, 50%, .5);

    --ck-color-suggestion-marker-deletion-border: hsla(345, 71%, 40%, .35);
    --ck-color-suggestion-marker-deletion-border-active: hsla(345, 71%, 25%, .5);
    --ck-color-suggestion-marker-deletion-background: hsla(345, 71%, 65%, .35);
    --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%);
    --ck-color-suggestion-box-format-border: hsl(191, 62%, 60%);

    /* Variables responsible for the styling of suggestions for widgets: */
    --ck-color-suggestion-widget-insertion-background: hsla(128, 71%, 65%, .05);
    --ck-color-suggestion-widget-insertion-background-active: hsla(128, 71%, 50%, .07);
    --ck-color-suggestion-widget-deletion-background: hsla(345, 71%, 65%, .05);
    --ck-color-suggestion-widget-deletion-background-active: hsla(345, 71%, 45%, .07);
    --ck-color-suggestion-widget-format-background: hsla(191, 90%, 40%, .09);
    --ck-color-suggestion-widget-format-background-active: hsla(191, 90%, 40%, .16);

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

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