Comments overview

The CKEditor 5 comments feature makes it possible to add comments to any part of the rich text content, including text and block elements such as embedded media or images. Comments would usually carry an explanation of what and why the author or editor did or wants to suggest. It may be a question about some unclear statement, remarks concerning facts or continuity errors, common mistakes, possible ways to expand a paragraph – all of these are always welcome and help improve the content.

# Demo

Test the comments feature in the editor below. Select a passage or a word you need to comment and use the toolbar button to add a comment. Use the sidebar to check the existing ones.

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.

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. You can read more about CKEditor 5’s collaboration features and their real life implementations in this dedicated blog post.

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

# Integration

# Use as a standalone plugin

The comments plugin does not require real-time collaboration to work. If you prefer a more traditional approach to document editing, the 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.

# Learn more

# Configuration

The configuration details for the comments feature can be found in the CommentsConfig API reference.

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

• The <comment-start> and <comment-end> tags are added if the comment starts/ends in text,
• otherwise, the 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 the 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>
</figure>

Note that if your application filters HTML content, for example to prevent XSS, you need to 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>
    <div id="sidebar"></div>
</div>

# Why comments content is not stored in the document data?

Note that the markers only store the comment thread IDs. They do not include any content for security reasons. If you stored the complete comment discussion with the editor content, a malicious user could edit it, including comments written by other authors. It would be very difficult to check which changes in the comments were done by the user when saving data. You would need to analyze the whole content of the document and compare it with 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 ensure that only authorized changes were introduced. For these reasons, adapter integration is the recommended solution.

However, if you want to save your content together with the comments data, check the 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 65000 characters. Note that comment content is stored in the HTML format, so the HTML tags (which are invisible for the user) use up some of the characters limit. If the limit is exceeded, the user interface will prevent the user from submitting the comment.

# API overview

Check the comments API documentation for detailed information about the comments API. Making yourself familiar with the API may help you understand the code snippets.

# Comments annotations customization

The comments annotations are highly customizable. Please refer to the Annotation customization guide to learn more.

# Comments-only mode

You can run the editor in the “comments-only” mode. In this mode, the user can add, edit and remove comments but is unable to edit the document content or change the document data otherwise.

# Comments for multiple editors

If your application displays multiple editors on one page, you might want to use the context feature. It will, among others, let you display comments from all editors inside one sidebar.

# Comments outside the editor

The comments feature can be also used on regular form fields or HTML elements. Thanks to that, you can allow for commenting on all elements of your application and provide a unified user experience and interface. See the Comments outside the editor guide to learn more.