Annotations in CKEditor 5 collaboration features

Annotations are a part of the collaboration features system which is responsible for managing and displaying UI elements (“balloons”) connected with comments and suggestions.

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

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

• Choose between the provided display modes (sidebars or inline annotations).
• Customize annotations created by comments and track changes plugins.
• Provide your own annotations for your custom plugins.
• Provide your own UI for annotations (for example, a custom sidebar with your own display logic).

# Annotations customization

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

• Theme customization.
• Configuration, including comment input field configuration.
• Providing a custom template for the default views.
• Providing your own custom view for 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.

// Get the annotations repository.
const annotations = editor.plugins.get( 'Annotations' );

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

// Add a new annotation to the collection.
import AnnotationView from '@ckeditor/ckeditor5-comments/src/annotations/view/annotationview';
import View from '@ckeditor/ckeditor5-ui/src/view';

class AnnotationInnerView extends View {
    constructor() {
        super();
        this.setTemplate( { tag: 'div' } );
    }
}

const annotationTarget = document.getElementById( 'my-annotation-target' );

const annotation = new Annotation( {
    view: new AnnotationView( new AnnotationInnerView() ),
    target: annotationTarget,
    type: 'comment'
} )

annotations.add( annotation );