CKEditor Ecosystem Documentation
Search
Report an issue
Home/CKEditor 5/Features

Annotations in CKEditor 5 collaboration features

Annotations are a part of the collaboration features system. They are UI elements (“balloons”) that correspond to comments and suggestions.

# Additional feature information

Features like comments and track changes create views (“balloons”) that represent their data. Such a view is called an annotation. They are added to and stored in the annotations plugin. Then, UI mechanisms (like sidebars or inline annotations) use the annotation views to populate themselves and create various types of user experiences.

Using the annotations system and the provided API, you can:

# Annotations customization

There are multiple levels on which you can modify the look of annotations:

Refer to the linked guides to learn more about how to customize annotations for collaboration features of CKEditor 5.

# API overview

The main entry point for all external actions should be the Annotations plugin. It stores annotations for all editors and allows manipulating them.

The example requires a working editor setup including collaboration features as a starting point. We recommend you re-use the setup from the comments feature integration guide. Please walk through the setup before moving to the example below.

In this example, the Annotation plugin API will be used to display a custom annotation. To do that, you should create a target element to which the annotation will be attached. In the index.html file created in the reference guide, add the following static <div> element next to the editor data container:

<!-- ... -->
<div id="editor"></div>
<div id="my-annotation-target">Custom annotation target</div>
<!-- ... -->

Now, in the main.js file of the project, please add the following code that creates the annotation:

import { View } from 'ckeditor5';

/* ... */

ClassicEditor
    .create(document.querySelector('#editor'), editorConfig)
    .then( editor => {
        // Get the annotations repository.
        const annotations = editor.plugins.get( 'Annotations' );

        // Add a callback fired whenever active annotations change.
        annotations.on( 'change:activeAnnotations', ( evt, name, newAnnotations, oldAnnotations ) => {
            console.log( newAnnotations );
        } );

        class AnnotationInnerView extends View {
            constructor() {
                super();
                this.setTemplate( {
                    tag: 'div',
                    children: [
                        'Annotation text'
                    ]
                } );
            }
        }

        const annotationTarget = document.getElementById( 'my-annotation-target' );
        const annotationView = annotations.createAnnotationView( editor.locale, new AnnotationInnerView() );

        const annotation = annotations.createAnnotation( {
            view: annotationView,
            target: annotationTarget,
            type: 'comment'
        } )

        annotations.add( annotation );
    } );

When you run the project, you should see the “Custom annotation target” element displayed below the editor. You should also see the annotation view with the “Annotation text” displayed in the sidebar.

The annotation was attached to a static DOM element for simplicity. In a real-world scenario, annotations are more likely to refer to the edited content (for example, view elements and related markers). Use the mapViewToDom() method to convert between view elements and DOM elements to use them as targets for createAnnotation().