Report an issue

guideComments overview

The comments feature makes it possible to add comments to any part of rich text content in CKEditor 5, including text and block elements such as embedded media or images.

Commented content is marked as highlighted and a corresponding comment balloon is displayed in the sidebar or inline. Comments can be added, edited, deleted and replied to, allowing the users to collaborate on the same document directly in the rich text editor.

Comment threads can be displayed in a sidebar or as inline balloons. See the Comments display mode guide to learn how to configure the display mode.

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

The comments feature can be used together with real-time collaboration or as a standalone plugin where the comments are saved in your application using a custom integration.

A comments-only mode is available, too, if you want to limit the user permissions and only allow them to add comments to the document, but not edit it directly.

# Use as a standalone plugin

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

To learn how to integrate comments as a standalone plugin, refer to the Integrating comments 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.

# Comments markup

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

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

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

Examples of the possible mark-up:

Comment on text:

    <p>They are <comment-start name="b39dd790"></comment-start>awesome<comment-end name="b39dd790"></comment-end>.</p>

Comment on an image:

<figure class="image" data-comment-end-after="b39dd790" data-comment-start-before="b39dd790">
    <img src="foo.jpg">
    <figcaption>Image caption.</figcaption>

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

Before version 21.0.0 comments boundaries were always marked by <comment> tags, which had id and type attributes, for example:

  • <comment id="e8ghd7" type="start"></comment>,
  • <comment id="gfdmk3:e3dkg" type="end"></comment>.

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

If you need to display the document data without the comments, you can simply remove the comments markup from the document data:

<p>They are awesome.</p>

When launching the editor, though, make sure to include comments markup in the HTML:

<div id="container">
    <div id="editor">
        <p>They are <comment-start name="b39dd790"></comment-start>awesome<comment-end name="b39dd790"></comment-end>.</p>
    <div id="sidebar"></div>

# Why is there no comments data in content?

Note that markers only store comment thread IDs. Why do they not include any content?

The reason is security. If you stored the whole comment discussion with the editor content, a malicious user could edit it, including comments written by other authors. It would be very hard to check which changes in the comments the user has done when saving data. You would need to analyze the whole content of the document and compare it to the previous version. Considering that both content and comments could change at the same time and they are mixed, it would be a hard task to be sure that only authorized changes were introduced. For these reasons, adapter integration is the recommended one.

However, if you want to save your content together with the comments data, check A simple “load and save” integration guide which should help you.

# Characters limit

For technical reasons, each comment in the thread has a character limit set to 4000 characters. Note that comment content is stored in the HTML format, so the HTML tags (which are invisible for the user) use up some characters. Nevertheless, the 4000 characters limit allows you to create a really long comment and should be sufficient for any use case. If the limit is exceeded, the user interface will prevent the user from submitting the comment.

# Comments feature customization

The comments feature is highly customizable. Please refer to the Annotation customization section and Comments API overview to learn more.