# Annotations in CKEditor 5 collaboration features

Annotations are UI elements (“balloons”) that correspond to comments and suggestions. Using the annotations plugin and its API, you can display them in a sidebar or inline, customize how they look, and even create your own annotations for custom plugins.

<a id="additional-feature-information">

## 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)](annotations-display-mode.md).
* [Customize annotations created by comments and track changes plugins](#annotations-customization).
* Provide custom annotations for your plugins.
* Provide custom UI for annotations (for example, a custom sidebar with your display logic).

<a id="annotations-customization">

## Annotations customization

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

* [Theme customization](annotations-custom-theme.md).
* [Configuration, including comment input field configuration](annotations-custom-configuration.md).
* [Providing a custom template for the default views](annotations-custom-template.md).
* [Providing a custom view for annotations](annotations-custom-view.md).

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

<a id="api-overview">

## API overview

The main entry point for all external actions should be the [`Annotations`](../../../api/module_comments_annotations_annotations-Annotations.md) plugin. It stores [annotations](../../../api/module_comments_annotations_annotation-Annotation.md) for all editors and allows manipulating them.

> **Note**
>
> 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](../comments/comments-integration.md#before-you-start) guide. Please walk through the setup before moving to the example below.

In this example, the [`Annotation` plugin API](../../../api/module_comments_annotations_annotations-Annotations.md) 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](../comments/comments-integration.md#before-you-start) guide, add the following static `<div>` element next to the editor data container:

```html
<!-- ... -->
<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:

**NPM**

```js
import { View } from 'ckeditor5';

ClassicEditor
	.create( {
		...editorConfig,
		attachTo: document.querySelector('#editor')
	} )
	.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 );
	} );
```

**CDN**

```js
const { View } = CKEDITOR;

ClassicEditor
	.create( {
		...editorConfig,
		attachTo: document.querySelector('#editor')
	} )
	.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.

> **Note**
>
> 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](../../../framework/architecture/editing-engine.md#element-types-and-custom-data) and related [markers](../../../framework/architecture/editing-engine.md#markers)). Use the [`mapViewToDom()`](../../../api/module_engine_view_domconverter-ViewDomConverter.md#function-mapViewToDom:ELEMENT) method to convert between view elements and DOM elements to use them as targets for [`createAnnotation()`](../../../api/module_comments_annotations_annotations-Annotations.md#function-createAnnotation).

---

Full index of the CKEditor 5 documentation: [llms.txt](../../../../llms.txt)