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:

• Choose between the provided display modes (sidebars or inline annotations).
• Customize annotations created by comments and track changes plugins.
• Provide custom annotations for your plugins.
• Provide custom UI for annotations (for example, a custom sidebar with your 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 a 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';
import { View } from '@ckeditor/ckeditor5-ui';

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 );