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:

  • <suggestion-start> and <suggestion-end> tags are added if the suggestion starts/ends in text,
  • otherwise, the following attributes are added on elements:
    • data-suggestion-start-before,
    • data-suggestion-end-after,
    • data-suggestion-start-after,
    • data-suggestion-end-before.

Also, <suggestion-td> tag is used for table cells pasting suggestions to separate old content (original) from the new content (pasted).

Read more about marker-to-data conversion to understand what data you may expect.

Examples of the possible mark-up:

Replacing word “chocolate” with word “ice-creams”:

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

Inserting image:

<figure class="image" data-suggestion-end-after="insertion:e1f0810:eohfu9" data-suggestion-start-before="insertion:e1f0810:eohfu9">
    <img src="foo.jpg">
    <figcaption>Image caption.</figcaption>
</figure>

Adding bold:

<p>
    This is
    <suggestion-start name="formatInline:fsao87:ekeij:e3404"></suggestion-start>
    important
    <suggestion-end name="formatInline:fsao87:ekeij:e3404"></suggestion-end>
    .
</p>

Pasting table cell with text “New” into a table cell with text “Old”:

<td ...>
    <suggestion-td data-suggestion-end-after="insertion:..." data-suggestion-start-before="insertion:...">
        <p>New</p>
    </suggestion-td>
    <suggestion-td data-suggestion-end-after="deletion:..." data-suggestion-start-before="deletion:...">
        <p>Old</p>
    </suggestion-td>
</td>

The data format for suggestion has changed in collaboration features version 21.0.0.

Before version 21.0.0 suggestions boundaries were always marked by <suggestion> tags, which had id, suggestion-type, type and optional count attributes, for example:

  • <suggestion id="e8ghd7:e390dk" suggestion-type="insertion" type="start"></suggestion>,
  • <suggestion id="e8ghd7:e390dk" suggestion-type="formatInline:i4u3xm" type="end" count="3erh"></suggestion>.

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

We are working on an API that will provide the functionality to get editor data with suggestions accepted or rejected directly from the editor.

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