Report an issue

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

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

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