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

# Saving data without suggestions

If you need to get the editor data with all the existing suggestions accepted or discarded, please refer to the dedicated guide.

# 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.